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1 . Introduction 


"What is Emacs? It is a tree falling in 
the forest with no one to hear it. It 
is a beautiful flower that smells 
awful . ' ’ 

This manual attempts to describe the Unix Implementation of Emacs, an 
extensible display editor. It is an editor in that it is primarily used for 
typing in and modifying documents, programs, or anything else that is 
represented as text. It uses a display to interact with the user, always 
keeping an accurate representation of what is happening visible on the screen 
that changes in step with the changes made to the document. The feature that 
distinguishes Emacs from most other editors is its extensibility, that is, a 
user of Emacs can dynamically change Emacs to suit his own tastes and needs. 

Calling this editor Emacs is rather presumptuous and even dangerous. There 
are two major editors called Emacs. The first was written at MIT for their ITS 
systems as an extension to TECO. This editor is the spiritual father of all 
the Emacs- like editors; it's principal author was Richard Stallman. The other 
was also written at MIT, but it was written in MacLisp for Multics by Bernie 
Greenberg. This editor picks up where ITS Emacs leaves off in terms of its 
extension facilities. Unix Emacs was called Emacs in the hope that the cries 
of outrage would be enough to goad the author and others to bring it up to the 
standards of what has come before. 

The organization of this manual is rather haphazard. Information useful to 
experts and novices is intermixed, although sections intended for experts are 
labeled. The first several sections were written hastily in an attempt to 
provide a general introduction to the commands in Emacs and to try to show the 
method in the madness that is the Emacs command structure. Subsequent sections 
describe the extension language and the more obscure commands. Beginning users 
may feel swamped by the volume of material in this manual. Fortunatly, they 
can ignore almost everything here. The best way to learn Emacs is to find a 
friend who already knows. The next best way is to sit down at a terminal, run 
Emacs, and try the learn command. Someday a tutorial introduction to Emacs 
should be written. 

This manual has an extensive index, I suggest that you make use of it. 

1.1. The Screen 

Emacs divides a screen into several areas called windows, at the bottom of 
the screen there is a one line area that is used for messages and questions 
from Emacs. Most people will only be using one window, at least until they 
become more familiar with Emacs. A window is displayed as a set of lines, at 
the bottom of each window is its mode line (For more information on mode lines 
see section 15, page 72) . The lines above the mode line contain an image of 
the text you are editing in the region around dot (or point) . Dot is the 
reference around which editing takes place. Dot is a pointer which points at a 
position between two characters. On the screen, the cursor will be positioned 
on the character that immediatly follows dot. When characters are inserted, 
they are inserted at the position where dot points; commands exist that delete 
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characters both to the left and to the right of dot. The text on the screen 
always reflects they way that the text looks now. 

/JUT i 

1.2. Invoking Emacs — /0gfr//oc*. / — j?u-f ■join's u. . 

Emacs is invoked as a Unix command by typing 

emacs files 

to the Shell (the Unix command interpreter) . Emacs will start up, editing the 
named files. You will probably only want to name one file. If you don't 
specify any names, Emacs will use the same names that it was given the last 
time that it was invoked. Gory details on the invocation of Emacs can be found 
in section 12.16, page 66. 

1.3. Entering Commands 

Normally, each character you type is interpreted individually by Emacs as a 
command. The instant you hit a key the command that it represents will be 
performed immediatly. 

Throughout this manual, characters which are used as commands are printed in 
bold face. They will sometimes have a control prefix which is printed as an 
uparrow character : is control-X and is typed by holding down the control 

(often labeled Ctrl on the top of the key) and simultaneously striking X. Some 
will have an escape (sometimes called meta) prefix which is usually printed 
thus: ESC-X and typed by striking the escape key (often labeled esc) then X. 
And some will have a ~X prefix which is printed ~XX which is typed by holding 
down the control key, striking X, releasing the control key then striking X 
again . 

For example, ESC-~J is typed by striking ESC then holding down the control 
key and striking J. 

Each command has a long name and by that long name may be bound to a key. 
Striking the key causes the associated command to be executed. For example, ~F 
is normally bound to the command named forward-character which moves dot 
forward one character. All of the usual printing characters are bound to a 
function (self-insert) that simply inserts the character into the current 
buffer . 

Even though the number of characters available to use for Emacs commands is 
large, there are still more commands than characters. You probably wouldn't 
want to bind them all to keys even if you could. There are many commands that 
are not normally bound to keys. These must be executed with the ESC-X command 
or by binding them to a key (via the bind-to-key command) . Heaven help the 
twit who rebinds ESC-X. 

The ESC-X command will print " on the last line of the display and expect 
you to type in the name of a command. Space and ESC characters may be struck 

to invoke Tenex style command completion (ie. you type in the first part of the 

command, hit the space bar, and Emacs will fill in the rest for you — it will 

complain if it can’t figure out what you're trying to say) . If the command 

requires arguments, they will also be prompted for on the bottom line. If you 



need help, typing '?' will often result in a list of the options available to 
you. 

1.4. Getting Help 

Emacs has many commands that let you ask Emacs for help about how to use 
Emacs. The simplest one is ESC-? (apropos) which asks you for a keyword and 
then displays a list of those commands whose full name contains the keyword as 
a substring. For example, to find out which commands are available for dealing 
with windows, type ESC-?, Emacs will ask "Keyword: " and you reply "window". A 
list like the following appears: 


beginr,ing-o f-window 

ESC- 

delete-othej — windows 

"Xl 

delete-window 

~XD 

end-o f-window 

ESC- 

en large-window 

~XZ 

1 ine-to-top-o f-window 

A A 

next-window 

~XN 

page-next-window 

ESC- 

previous-window 

~XP 

shr ink-window 

~x~z 

split-current-window 

~X2 


To get detailed information about some command, the describe-command command 
can be used. It asks for the name of a command, then displays the long 
documentation for it from the manual. For example, if you wanted more 

information about the shrink-window command, just type 

"ESC-Xdescribe-command shrink-window" and Emacs will reply: 

shr ink-w indow 

Makes the current window one line shorter, and the window 
(or the one above if there is no window below) one line ta 
Can’t be used if there is only one window on the screen. 

If you want to find out what command is bound to a particular key, 
describe-key will do it for you. Describe-bindings can be used to make a 
"wall chart' ' description of the key bindings in the currently running Emacs, 
taking into account all of the bindings you have made. 
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2 . Basic Commands 

All of the normal printing characters when struck just insert themselves into 
the buffer at dot. 

To move dot there are several simple commands. The arrow keys on a TVI 
move dot one space in the direction indicated. The arrow keys will be referred 
to as DOWN, UP, LEFT, and RIGHT. 

Incremental searches may be used to move dot by using the ~S command to search 
in the forward direction and ~R to search in the reverse direction. 


Deletions may be performed using delete (DEL) to delete the character to the 
left of dot and CHAR DELETE to delete the character to the right of dot. 


The following table summarizes all of the motion and deletion commands, 


Units of Motion 
Characters 
Words 
Intra line 
Inter line 


Direction 

Move 

Left 
LEFT 
ESC-LEFT 


UP 


Delete 

Right Left Right 

RIGHT delete CHAR DELETE 
ESC-RIGHT ESC-delete ESC-d 
A E LINE DELETE LINE ERASE 
DOWN 


2.1. Commands to move around with 


forward-character RIGHT 
Move dot forwards one character. Ends-of-lines and tabs each count as one 
character. You can't move forward to after the end of the buffer. 


forward-paragraph ESC-] 
Moves to the end of the current or following paragraph. Blank lines, and 
Scribe and nroff command lines separate paragraphs and are not parts of 
paragraphs . 


forward-sentence ESC-e 
Move dot forward to the beginning of the next sentence. Sentences are 
seperated by a '?' or '!' followed by whitespace. 


forward-word ESC-RIGHT 

Move dot forward to the end of a word. If not currently In the middle of a 
word, skip all intervening punctuation. Then skip over the word, leaving dot 
positioned after the last character of the word. A word is a sequence of 
alphanumerics . 



LEFT 
as one 


backward-character 

Move dot backwards one character. Ends-of-lines and tabs each count 

character. You can't move back to before the beginning of the buffer. 


backward-paragraph ESC- [ 

Moves to the beginning of the current or previous paragraph. Blank lines, 
and Scribe and nroff command lines separate paragraphs and are not parts of 
paragraphs . 


backward-sentence ESC-A 

Move dot backward to the beginning of the preceeding sentence; if dot is in 
the middle of a sentence, move to the beginning of the current sentence. 
Sentences are seperated by a '?' or '!* followed by whitespace. 


backward-word ESC-LEFT 

If in the middle of a word, go to the beginning of that word, otherwise go to 
the beginning of the preceding word. A word is a sequence of alphanumerics . 


goto-character number Expert 

Goes to the given charactei — position. (goto-character 5) goes to character 

position 5. 


next- line DOWN 

Move dot to the next line. ~N and A P attempt to keep dot at the same 
horizontal position as you move from line to line. 


next-page '"N 

Reposition the current window on the current buffer so that the next page of 
the buffer is visible in the window (where a page is a group of lines slightly 
smaller than a window) . In other words, it flips you forward a page in the 
buffer. Its inverse is "P. If possible, dot is kept where it is, otherwise it 
is moved to the middle of the new page. 


previous- line UP 

Move dot to the previous line. ^N and ^P attempt to keep dot at the same 
horizontal position as you move from line to line. 


previous-page *P 

Repositions the current window on the current buffer so that the previous 
page of the buffer is visible in the window (where a page is a group of lines 
slightly smaller than a window) . In other words, it flips you backward a page 
in the buffer. Its inverse is ~N. If possible, dot is kept where it is, 
otherwise it is moved to the middle of the new page. 
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track-eol-on-'N-'P variable 

If ON then DOWN and UP will "stick" to the end of a line if they are started 
there. If OFF DOWN and UP will try to stay in the same column as you move up 
and down even if you started at the end of a line, (default ON) Don’t ask why 
it has this name. 

move-dot-to-x-y numbei — x numbei — y Expert 

Switches to the buffer and sets dot to the positon of the character that was 
displayed at screen coordinates x,y. If x and y don't point to a valid 
character (eg. if they are out of bounds or point to a mode line) an error is 
flagged. 

This function is intended for use supporting mice and tablets. One way to do 
this is to have depressions of the tablet button generate a sequence of 
keystrokes that Emacs sees as normal tty input. If, for example, the tablet 
was to transmit the four charcters ESC-M-x-y when the button was depressed over 
character x,y then the following function would provide simple support for it: 

(defun (mouse-set-dot x y 

(setq x (get-tty-character) ) 

(setq y (get-tty-character) ) 

(move-dot-to-x-y x y) 

)) 

(bind-to-key "mouse-set-dot" "\eM") 


end-of-file ESC-> 

Move dot to just after the last character of the buffer. 


end-of-line ~E 
Move dot to the end of the line in the current buffer that contains dot; that 
is, to just after the following end-of-line or the end of the buffer. 


beginning-of-file ESC-< 

Move dot to just before the first character of the current buffer. 


beginning-of-line "A 

Move dot to the beginning of the line in the current buffer that contains 
dot; that is, to just after the preceeding end-of-line or the beginning of the 
buffer . 


2.2. Inserting text 
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insert-character number Expert 

Inserts its numeric argument into the buffer as a single character, 
(insert-character '0') inserts the character 'O' into the buffer. 


insert-string strings... Expert 

Inserts the strings that result from evaluating the given stringexpressions 
and inserts them into the current buffer just before dot. 


self-insert Expert 

This is tied to those keys which are supposed to self-insert. It is roughly 
the same as (insert-character (last-key-struck)) with the exception that it 
doesn't work unless it is bound to a key. 


left-margin variable 

The left margin for automatic text justification. After an automatically 
generated newline the new line will be indented to the left margin. 


left-offset variable 

The buffer specific offset between the left edge of the text and the left 
edge of the screen. It is normally 0: setting it to some value greater than 0 
has the effect of sliding the text in the window left by that many character 
positions. You should normally never use this variable. Use the commands 
dot-to- left-margin, dot-to-right-margin, and dot-to-centre . 


right -mar gin variable 

The right margin for automatic text justification. If a character is 
inserted at the end of a line and to the right of the right margin Emacs will 
automatically insert at the beginning of the preceding word a newline, tabs and 
spaces to indent to the left margin, and the prefix string. With the right 
margin set to something like (for eg.) 72 you can type in a document without 
worrying about when to hit the return key, Emacs will automatically do it for 
you at exactly the right place. 


prefix-string variable 

The string that is inserted after an automatic newline has been generated in 
response to going past the right margin. This is generally used by the 
language-dependent commenting features. (default ”") 


set-auto-fill-hook function-name Expert 

set-auto-fill-hook associates a command with the current buffer. When the 
right margin is passed by the attempt to insert some character the hook 
procedure for that buffer is invoked. The character that triggered the hook 
will not have been inserted, but will be inserted immediatly after the hook 
procedure returns [unless the procedure returns 0] . The hook procedure is 
responsible for maintaining the position of dot. last-key-struck may be usually 
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used to determine which character triggered the hook. If no hook procedure is 
associated with a buffer then the old action (break the line and indent) will 
be taken. This procedure may be used for such things as automatically putting 
boxes around paragraph comments as they are typed. 

2.3. Deleting things 


delete-next-character ~D or CHAR DELETE 
Delete the character immediatly following dot; that is, the character on 
which the terminals cursor sits. Lines may be merged by deleting newlines. 


kill-word ESC-D 

Delete characters forward from dot until the next end of a word. If dot is 
currently not in a word, all punctuation up to the beginning of the word is 
deleted as well as the word. 


delete-previous-character DEL 

Delete the character immediatly preceding dot; that is, the character to the 
left of the terminals cursor. If you've just typed a character, ~H (backspace) 
will delete it. Lines may be merged by deleting newlines. 


backward-kill-word ESC-DEL 
If not in the middle of a word, delete characters backwards (to the left) 
until a word is found. Then delete the word to the left of dot. A word is a 
sequence of alphanumerics . 


append-next-kill ESC-~W 
Append the next chunk of text that is killed to the last thing killed. The 
combined text may later be un-killed (yanked) as a unit. See kill-region 


kill-region ~W 
Wipe (kill, delete) all characters between dot and the mark. The deleted 
text is moved to the kill buffer, which is emptied first. The contents of 
the kill buffer may be retrieved later, usually to a new location in the file. 
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delete-white-space Expert 

Deletes all whitespace characters (spaces and tabs) on either side of dot. 


kill-to-end-of-line LINE ERASE 

Deletes characters forward from dot to the immediatly following end-of-line 
(or end of buffer if there isn't an end of line) . If dot is positioned at the 
end of a line then the end-of-llne character is deleted. Text deleted by this 
command is placed into the Kill buffer (which really is a buffer that you 
can look at) . All Kill commands normally erase the contents of the kill buffer 
first; subsequent Kills in an unbroken sequence append to the kill buffer. 


erase-buffer Expert 

Deletes all text from the current buffer. Doesn't ask to make sure if you 
really want to do it. 


erase-region Expert 

Erases the region between dot and mark. It is like delete-to-killbuf fer 
except that it doesn't move the text to the kill buffer. 

2.4. Markers 

Each buffer has a marker associated with it. A marker marks some position in 
the text for later reference. Commands exist to set the marker to the current 
position of 'dot' and to exchange the positions of dot and the mark. The 
region of text between dot and the mark is treated specially by certain 
commands . 


exchange-dot-and-mark "X"X 

Sets dot to the currently marked position and marks the old position of dot. 
Useful for bouncing back and forth between two points in a file; particularly 
useful when the two points delimit a region of text that is going to be 
operated on by some command like A W (erase region) . 


mark Expert 

Returns the position of the marker in the current buffer. An error is 
signaled if the marker isn't set. The value of the function is an object of 
type "marker" — if it is assigned to a variable then as changes are made to 
the buffer the variable's value continues to indicate the same position in the 
buffer . 


set-mark 

Puts the marker for this buffer at the place where dot is now, and leaves it 
there. As text is inserted or deleted around the mark, the mark will remain in 
place. Use ~X~X to move to the currently marked position. 
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dot Expert 

Returns the number of characters to the left of the current position of the 
cursor plus 1 (ie. if dot is at the beginning of the buffer, (dot) returns 1) . 
The value of the function is an object of type "marker" — if it is assigned to 
a variable then as changes are made to the buffer the variable's value 
continues to indicate the same position in the buffer. 

2.5. Moving things around 

Emacs has no commands explicitly for shuffling text around within a buffer. 
Rather you do it by killing a piece of next, moving somewhere else, and yanking 
it back. 


yank-from-killbuf fer ~Y 

Take the contents of the kill buffer and inserts it at dot in the current 
buffer. Dot is left after the inserted text. You will usually use ~K 
(kill-to-end-of-line) or (delete-to-killbuf fer) to get text into the 

killbuf fer . 


append-region-to-buf fer buffer — name Expert 

Appends the region between dot and mark to the named buffer. Neither the 
original text in the destination buffer nor the text in the region between dot 
and mark will be disturbed. 


copy-region-to-buf fer buffei — name Expert 

Copies the region between dot and mark to the named buffer. The buffer is 
emptied before the text is copied into it; the region between dot and mark is 
left undisturbed. 


prepend-region-to-buf fer buffei — name Expert 

Prepends the region between dot and mark to the named buffer. Neither the 
original text in the destination buffer nor the text in the region between dot 
and mark will be disturbed. 


region-to-string buffei — name Expert 

Returns the region between dot and mark as a string. Please be kind to the 
storage allocator, don't use huge strings. 


yank-buffer buffei — name ESC-~Y 
Take the contents of the buffer whose name is prompted for and insert it at 
dot in the current buffer. Dot is left after the inserted text. 
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transpose-characters 

Take the two characters preceding dot and exchange them. One of the most 
common errors for typists to make Is transposing two letters, typing "hte" when 
"the" is meant. '"T makes correcting these errors easy, especiallv if you can 
develop a ""T reflex". 

2.6. Changing Case 


case-region-capital ize Expert 

Capitalize all the words in the region between dot and mark by making their 
first characters upper case and all the rest lower case. 


case-region-invert Expert 

Invert the case of all alphabetic characters in the region between dot and 
mark . 


case-region-lower Expert 

Change all alphabetic characters in the region between dot and mark to lower 
case. 


case-region-upper Expert 

Change all alphabetic characters in the region between dot and mark to upper 
case. 


case-word-capital ize Expert 

Capitalize the current word (the one above or to the left of dot) by making 
its first character upper case and all the rest lower case. 


case-word-invert Expert 

Invert the case of all alphabetic characters in the current word (the one 
above or to the left of dot) . 


case-word-lower ESC-1 

Change all alphabetic characters in the current word (the one above or to the 
left of dot) to lower case. 


case-word-upper ESC-u 

Change all alphabetic characters in the current word (the one above or to the 
left of dot) to upper case. 
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3. Buffers and Windows 

There are two fundamental objects in Emacs, buffers and windows. A buffer is 
a chunk of text that can be edited, it is often the body of a file. A window 
is a region on the screen through which a buffer may be viewed. A window looks 
at one buffer, but a buffer may be on view in several windows. It is often 
handy to have two windows looking at the same buffer so that you can be looking 
at two separate parts of the same file, for example, a set of declarations and 
a piece of code that uses those declarations. Similarly, it is often handy to 
have two different buffers on view in two windows. 

3.1. Manipulating Buffers 


buffei — size Expert 

Returns the number of characters in the current buffer. 


current-buf fei — name Expert 

Returns the current buffer name as a string. 


delete-buffer buffei — name Expert 

Deletes the named buffer. All text that it contains will be thrown away. 
Deleting a buffer will only fail if it has an attached process that is actively 
running. 


list-buffers ~X~B 

Produces a listing of all existing buffers giving their names, the name of 
the associated file (if there is one) , the number of characters in the buffer 
and an indication of whether or not the buffer has been modified since it was 
read or written from the associated file. 


pop-to-buf fer buffei — name Expert 

Switches to a buffer whose name is provided and ties that buffer to a 
popped-up window. Pop-to-buf fer is exactly the same as switch-to-buf fer 
except that switch-to-buf fer ties the buffer to the current window, 

pop-to-buf fer finds a new window to tie it to. 


switch-to-buf fer buffei — name ^XB 

Prompt for the name of the buffer and associate it with the current window. 
The old buffer associated with this window merely loses that association: it is 
not erased or changed in any way. If the new buffer does not exist, it will be 
created, in contrast with ~X~0. 
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temp-use-buffer buffer — name Expert 

Switch to a named buffer without changing window associations. The commands 
pop-to-buf fer and switch-to-buf fer both cause a window to be tied to the 
selected buffer, temp-use-buffer does not. There are a couple of problems that 
you must beware when using this command: The keyboard command driver insists 
that the buffer tied to the current window be the current buffer, if it sees a 
difference then it changes the current buffer to be the one tied to the current 
window. This means that temp-use-buffer will be ineffective from the keyboard, 
switch-to-buf fer should be used instead. The other problem is that "dot" is 
really a rather funny concept. There is a value of "dot" associated with each 
window, not with each buffer. This is done so that there is a valid 
interpretation to having the same buffer visible in several windows. There is 
also a value of "dot" associated with the current buffer. When you switch to a 
buffer with temp-use-buffer, this "transient dot" is what gets used. So, if 
you switch to another buffer, then use temp-use-buffer to get back, "dot" will 
have been set to 1. You can use save-excursion to remember your position. 


use-old-buffer buffer — name 

Prompt for the name of the buffer and associate it with the current window. 
The old buffer associated with this window merely loses that association: it is 
not erased or changed in any way. The buffer must already exist, in contrast 
with ~XB. 


ask-about-buf fer — names variable 

The ask-about-buf fer — names variable controls what the visit-file command does 
if it detects a collision when constructing a buffer name. If 
ask-about-buf fer — names is true (the default) then Emacs will ask for a new 
buffer name to be given, or for <CR> to be typed which will overwrite the old 
buffer. If it is false then a buffer name will be synthesized by appending 
"<n>" to the buffer name, for a unique value of n. For example, if I 
visit-file "makefile" then the buffer name will be "makefile”; then if I 
visit-file "man/makefile" the buffer name will be "makefile<2>" . 


buffer — is-modified variable 

Buffer — is-modified is true iff the current buffer has been modified since it 
was last written out. You may set if OFF (ie. to 0) if you want Emacs to 
ignore the mods that have been made to this buffer — it doesn't get you back 
to the unmodified version, it just tells Emacs not to write it out with the 
other modified files. Emacs sets buffer — is-modified true any time the buffer 
is modified. 


read-only variable 

A buffer — specific variable which disallows any changes to the buffer when it 
is ON. (default: OFF) 
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3.2. Manipulating windows 


beginning-of-window ESC-, 
Move dot to just in front of the first character of the first line displayed 
in the current window. 


delete-othei — windows "XI 
Go back to one-window mode. Generally useful when Emacs has spontaneously 
generated a window (as for ESC-? or "X"B) and you want to get rid of it. 


delete-window "XD 

Removes the current window from the screen and gives it's space to it's 
neighbour below (or above) and makes the current window and buffer those of the 
neighbour . 


dot-is-visible Expert 

A function that is true iff dot is currently visible on the screen. 


end-of-window ESC-. 

Move dot to just after the last character visible in the window. 


enlarge-window "XZ 

Makes the current window one line taller, and the window below (or the one 
above if there is no window below) one line shorter. Can't be used if there is 
only one window on the screen. 


1 ine-to-top-o f-window 

What more can I say? This one is handy if you’ve just searched for the 
declaration of a procedure, and want to see the whole body (or as much of it 
as possible) . 

next-window "XN 
Switches to the window (and associated buffer) that is below the current 
window. 


page-next-window ESC-"V 

Repositions the window below the current one (or the top one if the current 
window is the lowest one on the screen) on the displayed buffer so that the 
next page of the buffer is visible in the window (where a page is a group of 
lines slightly smaller than a window) . In other words, it flips you forward a 
page in the buffer of the other window. 

If ESC-"V is given an argument it will flip the buffer backwards a page. 
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rather than forwards. So ESC-"V Is roughly equivalent to "V and "UESC-"V is 
roughly equivalent to ESC-V except that they deal with the other window. Yes, 
yes, yes. I realize that this is a bogus command structure, but I didn't 
invent it. Besides, you can learn to love it. 


previous-window ~XP 

Switches to the window (and associated buffer) that is above the current 
window. 


dot-to-left-margin ~X< 

Package shift. ml 

Does a horizontal scroll of the current window to move dot to the left 
margin . 


dot-to-rlght-margin ~X> 

Package shift. ml 

Does a horizontal scroll of the current window to move dot to the right 
margin. It won't move the left edge of the buffer farther right than the left 
edge of the window. 


dot-to-centre "X= 

Package shift. ml 

Does a horizontal scroll of the current window to move dot to the centre© f 
the window. It won't move the left edge of the buffer farther right than the 
left edge of the window. 


save-window-excursion Expert 

save-window-excursion is identical to save-excursion except that it also 
saves (in a rough sort of way) the state of the windows. That is, 
(save-window-excursion expressions...) saves the current dot, mark, buffer and 
window state, executes the expressions, restores the saved information and 
returns the value of the last expression evaluated. 

When the window state is saved Emacs remembers which buffers were visible. 
When it is restored, Emacs makes sure that exactly those buffers are visible. 
Emacs does not save and restore the exact layout of the windows: this is a 
feature, not a bug. 


shrink-window ~X"Z 

Makes the current window one line shorter, and the window below (or the one 
above if there is no window below) one line taller. Can't be used if there is 
only one window on the screen. 
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split-current-window "'X2 

Enter two-window mode. Actually, it takes the current window and splits it 
into two windows, dividing the space on the screen equally between the two 
v/indows. An arbitrary number of windows can be created — the only limit is on 
the amount of space available on the screen, which, sigh, is only 24 lines on 
most terminals available these days (with the notable exception of the Ann 
Arbor Ambassador which has 60) . 


window-height Expert 

Returns the number of text lines of a window that are visible on the screen. 


pop-up-windows variable 

If ON Emacs will try to use some window other than the current one when it 
spontaneously generates a buffer that it wants you to see or when you visit a 
file (it may split the current window) . If OFF the current window is always 
used. (default ON) 


split-height-threshhold variable 
Is the size of the smallest window that Emacs will consider splitting when 
it's allocating a new window. 

3.3. Manipulating the display 


message strings... Expert 

Displays the strings in the message region on the display (the line at the 
bottom) . 


redraw-display PAGE ERASE 
Clear the screen and rewrite it. This is useful if some transmission glitch, 
or a message from a friend, has messed up the screen. 


quick-redisplay variable 

If ON Emacs won't worry so much about the case where you have the same buffer 
on view in several windows — it may let the other windows be inaccurate for a 
short while (but they will eventually be fixed up) . Turning this ON speeds up 
Emacs substantially when the same buffer is on view in several windows. When 
it is OFF, all windows are always accurate. (default OFF) 


sit- for number Expert 

Updates the display and pauses for n/10 seconds. (sit- for 10) waits for one 
second. This is useful in such things as a Lisp auto-paren balencer. 
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scroll-one- line-down ESC-Z 

Repositions the current window on the current buffer so that the line which 
is currently the second to the last line in the window becomes the last 
— effectivly it moves the buffer down one line in the window. "Z is its 
inverse . 


scroll-one-line-up ~Z 

Repositions the current window on the current buffer so that the line which 
is currently the second line in the window becomes the first — effectivly it 
moves the buffer up one line in the window. ESC-Z is its inverse. 


scroll-step variable 

The number of lines by which windows are scrolled if dot moves outside the 
window. If dot has moved more than scroll-step lines outside of the window or 
scroll-step is zero then dot is centered in the window. Otherwise the window 
is moved up or down scroll-step lines. Setting scroll-step to 1 will cause the 
window to scroll by 1 line if you're typing at the end of the window and hit 
RETURN. 


wrap-long-lines variable 

If ON Emacs will display long lines by "wrapping" their continuation onto the 
next line (the first line will be terminated with a '\'). If OFF long lines 
get truncated at the right edge of the screen and a is display to indicate 

that this has happened. Wrap-long-lines is a buffer specific variable; when a 
buffer is created the default value will be used (set with setq-default) . 
(default ON) 


tab-size variable 

A buffei — specific variable which specifies the number of characters between 
tab stops. It's not clear that user specifiable tabs are a good idea, since 
the rest of Unix and most other DEC styled operating systems have the magic 
number 8 so deeply wired into them, (default 8) 


ctlchai — with- A variable 

If set ON control characters are printed as ~C (an ' character followed by 
the upper case alphabetic that corresponds to the control character) , otherwise 
they are printed according to the usual Unix convention ('\* followed by a 
three digit octal number) . (default OFF) 


visible-bell variable 

If ON Emacs will attempt to use a visible bell, usually a horrendous flashing 
of the screen, instead of the audible bell, when it is notifying you of some 
error. This is a more "socially acceptable" technique when people are working 
in a crowded terminal room. (default OFF) 
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send-string-to-terminal string Expert 

Sends the string argument out to the terminal with no conversion or 
interpretation. This should only be used for such applications as loading 
function keys when Emacs starts up. If you screw up the screen, Emacs won’t 
know about it and won't fix it up automatically for you — you'll have to type 
PAGE ERASE. 
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4. Reading and Writing files 

Buffers are associated with Unix files. A file may be read into or written 
from a buffer. The usual way to edit files is to visit them with "X'"'/ 
(visit-file) , and the usual way to write them with (write-modified- files) . 
Don't hesitate to edit many files at once, Emacs copes with this very well. 


visit-file file-name "X'V 

Visit-file asks for the name of a file and switches to a buffer that contains 
it. The file name is expanded to it's full absolute form (that is, it will 
start with a '/') • If no buffer contains the file already then Emacs will 
switch to a new buffer and read the file into it. The name of this new buffer 
will be just the last component of the file name (everything after the last '/' 
in the name) . If there is already a buffer by that name, and it contains some 
other file, then Emacs will ask "Enter a new buffer name or <CR> to overwrite 
the old buffer". For example, if my current directory is "/usr/jag/emacs" and 
I do a ~X~V and give Emacs the file name "../.emacs pro"then the name of the 
new buffer will be ".emacs pro" and the file name will be 
"/usr/ jag/. emacs pro". *X^V is the approved way of switching from one file to 
another within an invocation of Emacs. 


read-file file-name ~X~R 

Prompt for the name of a file; erase the contents of the current buffer; read 
the file into the buffer and associate the name with the buffer. Dot is set to 
the beginning of the buffer. 


write-current-file ~X~S 

Write the contents of the current buffer to the file whose name is associated 
with the buffer. 


write-file-exit ~U~X"Z 

Write all modified buffers to their associated files and if all goes well, 
Emacs will exit. 


wrlte-modified-files A X A M 

Write each modified buffer (as indicated by > 'X~B) onto the file whose name is 
associated with the buffer. Emacs will complain if a modified buffer does not 
have an associated file. 


write-named-file file-name ~X"W 

Prompt for a name; write the contents of the current buffer to the named 
file. 
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append-to-file file-name Expert 

Takes the contents of the current buffer and appends it to the named file. 
If the files doesn't exist, it will be created. 


current- file-name Expert 

Returns the file name associated with the current buffer as a string. If 
there is no associated file name, the null string is returned. 


expand-file-name file-name Expert 

Takes a string representing a file name and expands it into an absolute 
pathname. For example, if the current directory is "/usr/frodo" then 
(expand-file-name "../bilbo") will return "/usr/bilbo" . 


file-exists file-name Expert 

(file-exists fn) returns 1 if the file named by fn exists and is writable, 0 
if it does not exist, and -1 if it exists and is readable but not writable. 


file-modtime file-name Expert 

Returns the time of the last mod to the named file. 


insert-file file-name '"X^I 
Prompt for the name of a file and insert its contents at dot in the current 
buffer . 


unlink-file file-name Expert 

(unlink-file fn) attempts to unlink (remove) the file named fn. It returns 
true if the unlink failed. 


files-should-end-with-newline variable 

Indicates that when a buffer is written to a file, and the buffer doesn't end 
in a newline, then the user should be asked if they want to have a newline 
appended. It used to be that this was the default action, but some people 
objected to the question being asked, (default ON) 

4.1. Keeping backups 

Emacs will make a backup of a file just before the first time that it is 
overwritten. The backup will have the same name as the original, except that 
the string ".BAK" will be appended; unless the last name in the path has more 
than 10 characters, in which case it will be truncated to 10 characters, 
"foo.c" gets backed up on "foo.c.RAK"; "/usr/jag/foo.c" on 
"/usr/jag/foo.c.BAK"; and "EtherService .c" on "EtherServi .BAK" . The backup 
will only be made the first time that the file is rewritten from within the 
same invocation of Emacs, so if you write out the file several times the .BAK 
file will contain the file as it was before Emacs was invoked. The backup is 
normally made by fancy footwork with links and unlinks, to achieve acceptable 
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performance: when "foo.c" is to be rewritten, Emacs effectivly executes a "mv 
foo.c foo.c~" and then creates foo.c and writes the new copy. The file 
protection of foo.c is copied from the old foo.c, but old links to the file now 
point to the ~ file, and the owner of the new file is the person running 
Emacs . 


backup-by-copying variable 

If true, then when a backup of a file is made, rather than doing the fancy 
link/unlink footwork, Emacs copies the original file onto the backup. This 
preserves all link and owner information & ensures that the files I-number 
doesn't change (you're crazy if you worry about a files I-number) . 
Backup-by-copying incurs a fairly heafty performance penalty. (default OFF) 


backup-by-copy lng-when- linked variable 

If true, then when a backup of a file is made and the link count of the file 
is greater than 1, rather than doing the fancy link/unlink footwork, Emacs 
copies the original file onto the backup. If the link count is 1, then the 
link/unlink trick is pulled. This preserves link information when it is 
important, but still manages reasonable performance the rest of the time, 
(default OFF) 


backup-before-writing variable 

If ON, Emacs will back up the file automatically as needed. Otherwise, no 
backups will be made. (default ON) 

4.2. Checkpoint Files 

Every now and then Emacs will checkpoint all of the work that you have done 
so far. The checkpoint files are exact copies of the contents of the buffer 
you were working on at the time that the checkpoint happened. 


checkpoint 

Causes all modified buffers with 
checkpointed. This function 
checkpoint- frequency keystrokes. 


Expert 

an out of date checkpoint file to be 
is normally called automatically every 


checkpoint- frequency variable 

The number of keystrokes between checkpoints. Every "checkpoint- frequency" 
keystrokes all buffers which have been modified since they were last 
checkpointed are written to a file named "file%". "file" is the file name 
associated with the buffer, or if that is null, the name of the buffer. Proper 
account is taken of the restriction on file names to 14 characters. (default 
300) 
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needs-checkpointing variable 
A buffei — specific variable which if ON indicates that the buffer should be 
checkpointed periodically. If it is OFF, then no checkpoints will be done, 
(default ON) 


unlink-checkpoint-files variable 

If ON Emacs will unlink the corresponding checkpoint file after the master 
copy is written — this avoids having a lot of "%" files lying around but it 
does compromise safety a little. For example, as you're editing a file called 
''foo.c" Emacs will be periodically be writing a checkpoint file called 
" foo.c%" that contains all of your recent changes. When you rewrite the file 
(with ''ITX^Z or ~X"S for example) if uni ink-checkpoint- files is ON then the 
"%" file will be unlinked, otherwise it will be left. (default OFF) 
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5. Terminal types 

Grim reality being what it is, Emacs has to deal with a wide assortment of 
displays from many manufacturers. Each manufacturer has their own perverted 
idea of how programs should communicate with the display, so it is important 
for Emacs to correctly be told what type of terminal is being used. Under 

Unix, this is done by setting the environment variable 'TERM' . Normally, the 

operating system should set this to correspond to the type of terminal that you 
are using and you won't have to concern yourself with it. However, problems 
may arise and there are a few things that you should know. 

'TERM' is a string variable whose value is the name of the type of terminal 
that you are using. If you are using the standard Unix shell then it should be 
set using the commands: 

TERM=. . . 
export TERM 

If you're using the C shell (csh) then it should be set using the command: 
setenv TERM . . . 

where '...' is the appropriate terminal type. Consult your system 

administrator for a current list of valid terminal types. A good place to look 

is the file "/etc/termcap ' ' , it contains a list of all the terminals supported 
by Emacs. A few of the more common values are: 

concept-lnz For Concepts with the special firmware for Emacs. 

concept Concept 100, 104 and 108 's from HDS. 

hl9 For Heathkit or Zenith model 19 terminals. 

vtlOO For VTlOO's from DEC, or any of the thousands of look-alikes, 

aaa For the Ann Arbor Ambassador. 
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Emacs is capable of performing two kinds of searches . There are two 
parallel sets of searching and replacement commands that differ only in the 
kind of search performed. 

6.1. Simple searches 

The commands search- forward, search-reverse, query-replace-string and 
replace-string all do simple searches. That is, the search string that they 
use is matched directly against successive substrings of the buffer. The 
characters of the search string have no special meaning. These search forms 
are the easiest to understand and are what most people will want to use. They 
are what is conventionally bound to ~S, ~R, ESC-Q and ESC-R. 

6.2. Regular Expression searches 

The commands re-search- forward, re-search-reverse, re-query-replace-string, 
re-replace-string and looking-at all do regular expression searches. The 
search string is interpreted as a regular expression and matched against the 
buffer according to the following rules: 

1. Any character except a special character matches itself. Special 
characters are '\' '[' ' . 1 and sometimes N ~* 

2. A matches any character except newline. 

3. A 'V followed by any character except those mentioned in the 
following rules matches that character. 

4. A '\w' Matches any word character, as defined by the syntax tables. 

5. A '\W' Matches any non-word character, as defined by the syntax 
tables.- 

6. A '\b' Matches at a boundary between a word and a non-word 
character, as defined by the syntax tables. 

7. A '\B' Matches anywhere but at a boundary between a word and a 
non-word character, as defined by the syntax tables. 

8. A '\' ’ Matches at the beginning of the buffer. 

9. A '\' ' Matches at the end of the buffer. 

10. A '\<' Matches anywhere before dot. 

11. A '\>' Matches anywhere after dot. 

12. A '\=' Matches at dot. 

13. A nonempty string s bracketed "[ s ]*' (or " [~ s ]*' matches any 
character in (or not in) s. In s, '\' has no special meaning, and 
'] ' may only appear as the first letter. A substring a-b, with a and 
b in ascending ASCII order, stands for the inclusive range of ASCII 
characters . 

14. A '\' followed by a digit n matches a copy of the string that the 
bracketed regular expression beginning with the n th '\(* matched. 

15. A regular expression of one of the preceeding forms followed by 
matches a sequence of 0 or more matches of the regular expression. 

16. A regular expression, x, bracketed "\( x \) ' ' matches what x 


1 

Regular and Vanilla for those of you with no taste 
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matches . 

17. A regular expression of this or one of the preceeding forms, x, 
followed by a regular expression of one of the preceeding forms, y 
matches a match for x followed by a match for y, with the x match 
being as long as possible while still permitting a y match. 

18. A regular expression of one of the preceeding forms preceded by "' 

(or followed by '$'), is constrained to matches that begin at the 
left (or end at the right) end of a line. 

19. A sequence of regular expressions of one of the preceeding forms 
seperated by '\|'s matches any one of the regular expressions. 

20. A regular expression of one of the preceeding forms picks out the 
longest amongst the leftmost matches if searching forward, rightmost 
if searching backward. 

21. An empty regular expression stands for a copy of the last regular 
expression encountered. 

In addition, in the replacement commands, re-query-replace-string and 

re-replace-string, the characters in the replacement string are specially 

interpreted : 

- Any character except a special character is inserted unchanged. 

- A '\' followed by any character except a digit causes that character 
to be inserted unchanged. 

- A '\* followed by a digit n causes the string matched by the nth 
bracketed expression to be inserted. 

- An '&' causes the string matched by the entire search string to be 
inserted. 

The following examples should clear a little of the mud: 

Pika Matches the simple string "Pika' ' . 

Whiskey .* Jack Matches the string "Whiskey'', followed by the longest 

possible sequence of non-newline characters, followed by the 
string "Jack''. Think of it as finding the first line that 
contains the string "Whiskey*' followed eventually on the same 
line by the string "Jack'' 

[a-z] [a-z] * Matches a non-null sequence of lower case alphabetics. Using 

this in the re-replace-string command along with the 
replacement string "(&)'' will place parenthesis around all 
sequences of lower case alphabetics. 

Guiness\ | Bass Matches either the string 'Guiness' or the string 'Bass'. 

\Bed\b Matches 'ed' found as the suffix of a word. 

\bsi 1 ly\W* twit\b 

Matches the sequence of words 'silly' and 'twit' seperated by 
arbitrary punctuation. 
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6.3. String Search Commands 


search- forward search-string 

Prompt for a string and search for a match in the current buffer, moving 
forwards from dot, stopping at the end of the buffer. Dot is left at the end 
of the matched string if a match is found, or is unmoved if not. 


search-reverse search-string 

Prompt for a string and search for a match in the current buffer, moving 
backwards from dot, stopping at the beginning of the buffer. Dot is left at 
the beginning of the matched string if a match is found, or is unmoved if not. 


re-search- forward search-string Expert 

re-search- forward is identical to search- forward except that the search 
string is a regular expression rather than an uninterpreted sequence of 
characters . 


re-search-reverse search-string Expert 

re-search-reverse is identical to search-reverse except that the search 
string is a regular expression rather than an uninterpreted sequence of 
characters . 


case- fold-search variable 
If set ON all searches will ignore the case of alphabetics when doing 
comparisons. (default OFF) 


region-around-match number Expert 

Region-around-match sets dot and mark around the region matched by the last 

search. An argument of n puts dot and mark around the n'th subpattern matched 

by '\(' and '\) This can then be used in conjuction with region-to-string to 
extract fields matched by a patter. For example, consider the following 
fragment that extracts user names and host names from mail addresses: 

(re-search- forward "\\ ( [a-z] [a-z] *\\) *@ *\\ ( [a-z] [a-z] *\\) ") 
(region-around-match 1) 

(setq username (region-to-string) ) 

(region-around-match 2) 

(setq host (region-to-string) ) 

Applying this MLisp code to the text "send it to jag@vlsi" would set the 

variable 'username' to "jag" and 'host' to "vlsi" . 

You mustn't change the buffer between the time you do the search and 
the time you call region-around-match. 



31 


looking-at search-string Expert 

looking-at is true iff the given regular expression search string matches the 
text immediatly following dot. This is for use in packages that want to do a 
limited sort of parsing. For example, if dot is at the beginning of a line 
then (looking-at "[ \t]*else]) will be true if the line starts with an "else". 

6.4. String Replacement Commands 


query-replace-string search-string new-string ESC-q 

Replace all occurrences of one string with another, starting at dot and 
ending at the end of the buffer. Emacs prompts for an old and a new string in 
the minibuffer (the line at the bottom of the screen) . 

For each occurrence of the old string, Emacs requests that the user type in a 
character to tell it what to do (dot will be positioned just after the found 
string) . The possible replies are: 


<space> 

n 

r 


; 






Change this occurrence and continue to the next. 

Don't change this occurrence, but continue to the next 
Enter a recursive-edit. This allows you to make some 
local changes, then continue the query-replace-string by 
typing ~C . 

Change this occurrence and all the rest of the occurrences 
without bothering to ask. 

Change this one and stop: don't do any more replaces. 

Don't change this occurrence and stop: don't do any more 
replaces . 

(or anything else) Print a short list of the query /replace 
options . 


re-query-replace-string search-string new-string Expert 

re-query-replace-string is Identical to query-replace-string except that the 
search string is a regular expression rather than an uninterpreted sequence of 
characters . 


re-replace-string search-string new-string Expert 

re-replace-string is identical to replace-string except that the search 
string is a regular expression rather than an uninterpreted sequence of 
characters . 


replace-string search-string new-string ESC-r 

Replace all occurrences of one string for another, starting at dot and ending 
and the end of the buffer. Emacs prompts for an old and a new string in the 
minibuffer (the line at the bottom of the screen) . Unlike query-rep lace-string 
Emacs doesn't ask any questions about particular occurrences, it just changes 
them. Dot will be left after the last changed string. 
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replace-case variable 

If ON Emacs will alter the case of strings substituted with replace-string or 
query-replace-string to match the case of the original string. For example, 
replacing "which" by "that" in the string "Which is silly" results in "That is 
silly"; in the string "the car which is red" results in "the car that is red"; 
and in the string "WHICH THING?" results in "THAT THING?". 
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7. Compiling programs 

One of the most powerful features of Unix Emacs is the facility provided for 
compiling programs and coping with error messages from the compilers. It 
essential that you understand the standard Unix program make (even if you don't 
use Emacs) . This program takes a database (a makefile) that describes the 
relationships among files and how to regenerate (recompile) them. If you have 
a program that is made up of many little pieces that have to be individually 
compiled and carefully crafted together into a single executable file, make can 
make your life orders of magnitude easier; it will automatically recompile only 
those pieces that need to be recompiled and put them together. Emacs has a set 
of commands that gracefully interact with this facility. 

The ~X~E (compile-it) command writes all modified buffers and executes the 
make program. The output of make will be placed into a buffer called Error log 
which will be visible in some window on the screen. As soon as make has 
finished Emacs parses all of its output to find all the error messages and 
figure out the files and lines referred to. All of this information is 
squirreled away for later use by the command. 

The "'X^M (next-error) command takes the next error message from the set 
prepared by "X'E and does three things with it: 

- Makes the message itself visible at the top of a window. The buffer 
will be named Error log. 

- Does a visit (see the "X~V command) on the file in which the error 
occurred . 

- Sets dot to the beginning of the line where the compiler saw the 
error. This setting of dot takes into account changes to the file 
that may have been made since the compilation was attempted. Emacs 
perfectly compensates for any changes that may have been made and 
always positions the text on the correct line (well, correct as far 
as the compiler was concerned; the compiler itself may have been a 
trifle confused about where the error occurred) 

If you've seen all the error messages ~X~N will say so and do nothing else. 

So, the general scenario for dealing with programs is: 

- Build a make database to describe how your program is to be compiled. 

- Compile your program from within Emacs by typing ~X~E. 

- If there were errors, step through them by typing ~X^N, correcting 
the error, and typing ~X~N to get the next. 

- When you run out of error messages, type ~X~E to try the compilation 
again . 

- When you finally manage to get your beast to compile without any 
errors, type to say goodbye to Emacs. 

- You'll probably want to use sdb, the symbolic debugger, to debug your 
program. 

The ~X~E command doesn't always execute the make program: if it is given a 
non-zero argument it will prompt for a Unix command line to be executed in 
place of make. All of the other parts of '‘X'^E are unchanged, namely it still 
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writes all modified buffers before executing the command and parses the output 

of the command execution for line numbers and file names. 

This can be used in some very powerful ways. For example, consider the grep 
program. Typing "' , U / 'X''Egrep -n MyProc *.cESC" will scan all C programs in the 
current directory and look for all occurrences of the string "MyProc". After 
grep has finished you can use Emacs (via the '"X^N command) to examine and 
possibly change every instance of the string from a whole collection of files. 
This makes the task of changing all calls to a particular procedure much 
easier. Note: this only works with the version of grep in /usr/jag/bin which 
has been modified to print line numbers in a format that Emacs can understand. 

There are many more uses. The lint program, for example. Scribe users might 
find "cat MyReport .otl" to be useful. 

A file name/line number pair is just a string embedded someplace in the text 
of the error log that has the form "FileName, line LineNumber". The FileName 
may or may not be surrounded by quotes (") . The critical component is the 
string ", line " that comes between the file name and the line number. Roll 
your own file scanning programs, it can make your life much easier. 


next-error "X~N 

Take the next error message (as returned from the "X~E (compile) command) , do 
a visit (''X'Vj on the file in which the error occurred and set dot to the line 
on which the error occurred. The error message will be displayed at the top of 
the window associated with the Error log buffer. 


parse-erroi — messages-in-region Expert 

Parses the region between dot and mark for error messages (as in the 
compile-it ("X^E) command) and sets up for subsequent invocations of next-error 
(''X'N) . See the description of the compile-it command, and section 7 (page 
33) . 


compile-it ~X~E 

Make is a standard Unix program which takes a description of how to compile a 
set of programs and compiles them. The output of make (and the compilers it 
calls) is placed in a buffer which is displayed in a window. If any errors 
were encountered, Emacs makes a note of them for later use with ~X~N. 
Presumably, a data base has been set up for make that causes the files which 
have been edited to be compiled. ''X^E then updates the files that have been 
changed and make does the necessary recompilations, and Emacs notes any errors 
and lets you peruse them with ''X'^N. 

If ~X~E is given a non-zero argument, then rather than just executing make 
Emacs will prompt for a Unix command line to be executed. Modified buffers 
will still be written out, and the output will still go to the Error log buffer 
and be parsed as error messages for use with ~X~N. One of the most useful 
applications of this feature Involves the grep program. ""U^X^Egrep -n MyProc 
*.cESC" will scan through all C source files looking for the string "MyProc" 
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(which could be the name of a procedure) . You can then use '"X / 'N to step 
through all places in all the files where the string was found. Note: The 
version of grep in my bin directory, /usr/jag/bin/grep, must be used: it prints 
line numbers in a format that is understood by Emacs. (ie. "FileName, line 
LineNumber) 



36 


8. Abbrev mode 

Abbrev mode allows the user to type abbreviations into a document and have 
Emacs automatically expand them. If you have an abbrev called "rhp” that has 
been defined to expand to the string "rhinocerous party” and have turned on 
abbrev mode then typing the first non-alphanumeric character after having typed 
”rhp" causes the string "rhp" to be replaced by "rhinocerous party". The 
capitalization of the typed in abbreviation controls the capitalization of the 
expansion: "Rhp" would expand as "Rhinocerous party" and "RHP" would expand as 

"Rhinocerous Party" . 

Abbreviations are defined in abbrev tables. There is a global abbrev table 
which is used regardless of which buffer you are in, and a local abbrev table 
which is selected on a buffer by buffer basis, generally depending on the major 
mode of the buffer. 

Define-global-abbrev takes two arguments: the name of an abbreviation and the 
phrase that it is to expand to. The abbreviation will be defined in the global 
abbrev table. Define-local-abbrev is like define-global-abbrev except that it 
defines the abbreviation in the current local abbrev table. 

The use-abbrev-table command is used to select (by name) which abbrev table 
is to be used locally in this buffer. The same abbrev table may be used in 
several buffers. The mode packages (like electric-c and text) all set up 
abbrev tables whose name matches the name of the mode. 

The switch abbrev-mode must be turned on before Emacs will attempt to expand 
abbreviations. When abbrev-mode is turned on, the string "abbrev" appears in 
the mode section of the mode line for the buffer. Use-abbrev-table 

automatically turns on abbrev-mode if either the global or new local abbrev 
tables are non-empty. 

All abbreviations currently defined can be written out to a file using the 
write-abbrev-file command. Such a file can be edited (if you wish) and later 
read back in to define the same abbreviations again. Read-abbrev-file reads in 
such a file and screams if it cannot be found, quiet ly-read-abbrev- file doesn't 
complain (it is primarily for use in startups so that you can load a 
current-directory dependant abbrev file without worrying about the case where 
the file doesn't exist) . 

People writing MLisp programs can have procedures invoked when an abbrev is 
triggered. Use the commands define-hooked-global-abbrev and define-hooked- 
local-abbrev to do this. These behave exactly as the unhooked versions do 
except that they also associate a named command with the abbrev. When the 
abbrev triggers, rather than replacing the abbreviation with the expansion 
phrase the hook procedure is invoked. The character that trigged the abbrev 
will not have been inserted, but will be inserted immediatly after the hook 
procedure returns [unless the procedure returns 0] . The abbreviation will be 
the word immediatly to the left of dot, and the function abbrev-expansion 
returns the phrase that the abbrev would have expanded to. 
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define-global-abbrev abbrev phrase Expert 

Define (or redefine) an abbrev with the given name for the given phrase in 
the global abbreviation table. 


define-hooked-global-abbrev abbrev phrase function-nameExpert 

The commands define-hooked-global-abbrev and define-hooked-local-abbrev 
behave exactly as the unhooked versions do (define-global-abbrev and 
define-local-abbrev) except that they also associate a named command with the 
abbrev. When the abbrev triggers, rather than replacing the abbreviation with 
the expansion phrase the hook procedure is invoked. The character that trigged 
the abbrev will not have been Inserted, but will be Inserted immediatly after 
the hook procedure returns [unless the procedure returns 0] . The abbreviation 
will be the word immediatly to the left of dot, and the function 
abbrev-expansion returns the phrase that the abbrev would have expanded to. 


define-hooked-local-abbrev abbrev phrase function-nameExpert 
See the description of define-hooked-global-abbrev. 


define-local-abbrev abbrev phrase Expert 

Define (or redefine) an abbrev with the given name for the given phrase in 
the local abbreviation table. A local abbrev table must have already been set 
up with use-abbrev-table. 


quietly-read-abbrev-file file-name Expert 

Read in and define abbrevs appearing in a named file. This file should have 
been written using write-abbrev-file . Unlike read-abbrev-file, an error 
message is not printed if the file cannot be found. 


read-abbrev-file file-name Expert 

Read in and define abbrevs appearing in a named file. This file should have 
been written using write-abbrev-file. An error message is printed if the file 
cannot be found . 


use-abbrev-table table-name Expert 

Sets the current local abbrev table to the one with the given name. Local 
abbrev tables are buffer specific and are usually set depending on the major 
mode. Several buffers may have the same local abbrev table. If either the 
selected abbrev table or the global abbrev table have had some abbrevs defined 
in them, abbrev-mode is turned on for the current buffer. 
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write-abbrev-file fils-name Expert 

Write all defined abbrevs to a named file. This file is suitable for reading 
back with read-abbrev-file. 
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9. Communicating with Unix 


filtei — region she 11 -command-string Expert 

Take the region between dot and mark and pass it as the standard input to the 
given command line. Its standard output replaces the region between dot and 
mark. Use this to run a region through a Unix style- f ilter . 


fast-filtei — region shell-command-string Expert 

Is almost the same as filter — region except that it doesn't call the shell to 
parse the command. Instead, Emacs parses the command itself, simply breaking 
it up whereever there are spaces, and execs the program directly. This speeds 
up the function considerably. It should only be used by MLisp functions. 


execute-monitoi — command shell-command-string ~X! 

Prompt for a Unix command then execute it, placing its output into a buffer 
called Command execution and making that buffer visible in a window. The 
command will not be able to read from its standard input (it will be connected 
to /dev/null) . For now, there is no way to execute an interactive subprocess. 


return-to-monitor ESC- ! 

Recursivly invokes a new shell, allowing the user to enter normal shell 
commands and run other programs. Return to Emacs by exiting the shell; ie. by 
typing ~D. 


pause-emacs Expert 

Pause, giving control back to the superior shell using the job control 
facility of Berkeley Unix. The screen is cleaned up before the shell regains 
control, and when the shell gives control back to Emacs the screen will be 
fixed up again. Users of the sea-shell (csh) will probably rather use this 
command than "return-to-monitor", which is similar, except that it recursivly 
invokes a new shell. 


shell 

Package process. ml 

The shell command is used to either start or reenter a shell process. When 
the shell command is executed, if a shell process doesn’t exist then one is 
created (running the standard "sh'') tied to a buffer named "shell'. In any 
case, the shell buffer becomes the current one and dot is positioned at the end 
of it. In that buffer output from the shell and programs run with it will 
appear. Anything typed into it will get sent to the subprocess when the return 
key is struck. This lets you interact with a shell using Emacs, and all of 
it's editing capability, as an intermediary. You can scroll backwards over a 
session, pick up pieces of text from other places and use them as input, edit 
while watching the execution of some program, and much more... 
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system-name Expert 

Returns the name of the system on which Emacs is being run. This should be 
the ArpaNet or EtherNet (or whatever) host name of the machine. 


users-ful 1-name Expert 

Returns the users full name as a string. [Really, it returns the contents of 
the gecos field of the passwd entry for the current user, which is used on many 
systems for the users full name.] 


users- login-name Expert 

Returns the users login name as a string. 


working-directory Expert 

Returns the pathname of the current working directory. 


baud-rate Expert 

Returns what Emacs thinks is the baud rate of the communication line to the 
terminal. The baud rate is (usually) 10 times the number of characters 
transmitted ber second. (Baud-rate) can be used for such things as 

conditionally setting the display- file-percentage variable in your Emacs 
profile: (setq display- file-percentage (> (baud-rate) 600)) 


change-directory file-name Expert 

Changes the current directory (for Emacs) to the named directory. All future 
file write and reads (~X~S, ~X~V, etc.) will be interpreted relative to that 
directory. 


cur rent- time Expert 

Returns the current time of day as a string in the format described in 
CTIME(3), with the exception that the trailing newline will have been stripped 
off. (substr (current-time) -4 4) is the current year. 


current-numeric-time Expert 

Returns the current time of day as an integer in seconds since 00:00:00 GMT, 
Jan. 1, 1970; the standard Unix time format. 
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10. Details about the Help commands 


he lp-on-command-comp let ion-error variable 

If ON Emacs will print a list of possibilities when an ambiguous command is 
given, otherwise it just rings the bell and waits for you to type more, 
(default ON) 

doc 

Allows menu-type access to most of the help which Emacs can offer. To see 
the menu, type a "?" after the (control-underscore) . 

apropos string ESC-? 

Prompts for a keyword and then prints a list of those commands whose short 
description contains that keyword. For example, if you forget which commands 
deal with windows, just type "ESC-?windowESC" . 

describe-bindings 

Places in the Help window a list of all the keys and the name of the 
procedure that they are bound to. This listing is suitable for printing and 
making you own quick-reference card for your own customized version of Emacs. 

describe-command function-name 

Package DescribeX.ml 

Uses the Info system to describe some named command. You will be prompted in 
the minibuf for the name of a command and then Info will be invoked to show you 
the manual entry describing it. You can then use Info to browse around, or 
simply type ~C to resume editing. 


describe-key keystroke-string 

Describe the given key. ESC-Xdescribe-key ESC-X will print a short 
descrition of the ESC-X key. It tells you the name of the command to which the 
key is bound. To find out more about the command, use describe-command. 


describe-variable variable-name 

Package DescribeX.ml 

Uses the Info system to describe some named variable. You will be prompted 
in the minibuf for the name of a variable and then Info will be invoked to show 
you the manual entry describing it. You can then use Info to browse around, or 
simply type ^C to resume editing. 


describe-word- in-buffer "X"D 

Package DesWord. ml 

Takes the word nearest the cursor and looks it up in a data base and prints 
the information found. This data base contains short one- line descriptions of 
all of the Unix standard procedures and Franz Lisp standard functions. The 
idea is that if you've just typed in the name of some procedure and can't quite 
remember which arguments go where, just type "X~D and Emacs will try to tell 
you. 
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11. Undoing 


new-undo "X"U 

Package undo. ml 

The new-undo command, which is usually bound to ~X~U allows the user to 
interactively undo the effects of previous commands. Typing ~X~U undoes the 
effects of the last command typed. It will then ask "Hit <space> to undo 
more", each <space> that you then hit will undo one more command. Typing 
anything but space will terminate undoing. If it is terminated with anything 
other than <return> the termination character will be executed just as though 
it were a normal command. new-undo is an undoable command, just like the 
others, so if you find that you've undone too much just type ^X^U again to undo 
the undo's. 


undo Expert 

Undoes the effects of the last command typed. Arbitrarily complicated 
commands may be undone successfully. Only the buffer modifying effects of a 
command may be undone — variable assignments, key bindings and similar 
operations will not be undone. Even 'undo' may be undone, so executing undo 
twice in a row effectivly does nothing. 


undo-boundary Expert 

undo-boundary lays down the boundary between two undoable commands. When 
commands are undone, a 'command' is considered to be the series of operations 
between undo boundaries. Normally, they are laid down between keystrokes but 
MLisp functions may choose to lay down more. 


undo-more Expert 

Undoes one more command from what was last undone, undo-more must be 
preceeded by either an undo or an undo-more. This is usually used by first 
invoking undo to undo a command, then invoking undo-more repeatedly to undo 
more and more commands, until you've retreated to the state you want to be back 
to. 
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12. Extensibility 

Unix Emacs has two extension features: macros and a built in Lisp system. 
Macros are used when you have something quick and simple to do. Lisp is used 
when you want to build something fairly complicated like a new language 
dependant mode. 

12.1. Macros 

A macro is just a piece of text that Emacs remembers in a special way. When 
a macro is executed the characters that make up the macro are treated as though 
they had been typed at the keyboard. If you have some common sequence of 
keystrokes you can define a macro that contains them and instead of retyping 
them just call the macro. There are two ways of defining macros: 

The easiest is called a keyboard macro. A keyboard macro is defined by 
typing the start-remembering command (~X() then typing the commands which you 
want to have saved (which will be executed as you type them so that you can 
make sure that they are right) then typing the stop-remembering command ("X)). 
To execute the keyboard macro just type the execute-keyboard-macro command 
(~Xe) . You can only have one keyboard macro at a time. If you define a new 
keyboard macro the old keyboard macro vanishes into the mist. 

Named macros are slightly more complicated. They have names, just like 
commands and MLisp functions and can be called by name (or bound to a key) . 
They are defined by using the de fine-string-macro command (which must be 
executed by typing ESC-Xde fine-string-macro since it isn't usually bound to a 
key) which asks for the name of the macro and it's body. The body is typed in 
as a string in the prompt area at the bottom the the screen and hence all 
special characters in it must be quoted by prefixing them with "Q. A named 
macro may be executed by typing ESC-Xname-of-macro or by binding it to a key 
with bind-to-key. 

The current keyboard macro can be converted into a named macro by using the 
de fine-keyboard-macro command which takes a name a defines a macro by that 
name whose body is the current keyboard macro. The current keyboard macro 
ceases to exist. 


define-buf fei — macro Expert 

Take the contents of the current buffer and define it as a macro whose name 
is associated with the buffer. This is how one redefines a macro that has been 
edited using edit-macro. 


de fine-keyboard-macro macro-name Expert 

Give a name to the current keyboard macro. A keyboard macro Is defined by 
using the ~X( and ~X) command; de fine-keyboard-macro takes the current keyboard 
macro, squirrels it away in a safe place, gives it a name, and erases the 
keyboard macro, de fine-string-macro is another way to define a macro. 
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de fine-string-macro macro-name Expert 

Define a macro given a name and a body as a string entered in the minibuffer. 

Note; to get a control character into the body of the macro it must be quoted 

with ~Q. de fine-keyboard-macro is another way to define a macro. 


edit-macro macro-name Expert 

Take the body of the named macro and place it in a buffer called Macro edit. 
The name of the macro is associated with the buffer and appears in the 
information bar at the bottom of the window. The buffer may be edited just 
like any other buffer (this is, in fact, the intent) . After the macro body has 
been edited it may be redefined using define-buf fe; — macro. 


start-remembering "X ( 

All following keystrokes will be remembered by Emacs. 


stop-remembering ~X) 
Stops remembering keystrokes, as initiated by ^X(. The remembered keystrokes 
are not forgotten and may be re-executed with ~XE. 


execute-keyboard-macro "Xe 

Takes the keystrokes remembered with ~X( and ~X) and treats them as though 
they had been typed again. This is a cheap and easy macro facility. For more 
power, see the de fine-string-macro, de fine-keyboard-macro and bind-to-key 
commands . 

12.2. MLisp — Mock Lisp 

Unix Emacs contains an interpreter for a language that in many respects 
resembles Lisp. The primary (some would say only) resemblance between Mock 
Lisp and any real Lisp is the general syntax of a program, which many feel is 
Lisp’s weakest point. The differences include such things as the lack of a 
cons function and a rather peculiar method of passing parameters. 


12.2.1. The syntax of MLisp expressions 

There are four basic syntactic entities out of which MLisp expressions are 
built. The two simplest are integer constants (which are optionally signed 
strings of digits) and string constants (which are sequences of characters 
bounded by double quote characters — double quotes are included by 

doubling them; is a one character string. The third are names which are 

used to refer to things; variables or procedures. These three are all tied 
together by the use of procedure calls. A procedure call is written as a left 
parenthesis, "('*, a name which refers to the procedure, a list of whitespace 
separated expressions which serve as arguments, and a closing right 
parenthesis, ") ' * . An expression is simply one of these four things; an 
integer constant, a string constant, a name, or a call which may itself be 
recursivly composed of other expressions. 
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String constants may contain the usual C excape sequences, "\n" is a newline, 
"\t" is a tab, "\r" is a carriage return, "\b" is a backspace, "\e" is the 
escape (033) character, "\nnn" is the character whose octal representation is 
nnn, and "~\c" is the control version of the character c. 

For example, the following are legal MLisp expressions: 

1 The integer constant 1. 

"hi” A two character string constant 

"\~X\~F" A two character string constant 

"""what?""" A seven character string constant 

(+22) An invocation of the "+" function with integer arguments 2 and 

2. "+” is the usual addition function. This expression 

evaluates to the integer 4. 

(setq bert (* 4 12)) 

An invocation of the function setq with the variable bert as 
its first argument and and expression that evaluates the 
product of 4 and 12 as its second argument. The evaluation of 
this expression assigns the integer 48 to the variable bert. 

(visit-file "mbox") 

An invocation of the function visit-file with the string "mbox" 
as its first argument. Normally the visit-file function is 
tied to the key ~X~B. When it is invoked interactively, either 
by typing ~X~B or ESC-Xvisit-file, it will prompt in the 
minibuf for the name of the file. When called from MLisp it 
takes the file name from the parameter list. All of the 
keyboard-callable function behave this way. 

Names may contain virtually any character, except whitespace or parens and 
they cannot begin with a digit, "" ' * or ' ' . 


12.2.2. The evaluation of MLisp expressions 

Variables must be declared (bound) before they can be used. The 
declare-global command can be used to declare a global variable; a local is 
declared by listing it at the beginning of a progn or a function body (ie. 
immediatly after the function name or the word progn and before the executable 
statements) . For example: 

(de fun 

(foo i 

(setq i 5) 

) 

) 
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defines a rather pointless function called foo which declares a single local 
variable i and assigns it the value 5. Unlike real Lisp systems, the list of 
declared variables is not surrounded by parenthesis. 

Expressions evaluate to values that are either integers, strings or markers. 
Integers and strings are converted automaticly from one to the other type as 
needed: if a function requires an Integer parameter you can pass it a string 
and the characters that make it up will be parsed as an integer; similarly 

passing an integer where a string is required will cause the integer to be 

converted. Variables may have either type and their type is decided 
dynamically when the assignment is made. 

Marker values indicate a position in a buffer. They are not a character 

number. As insertions and deletions are performed in a buffer, markers 

automatically follow along, maintaining their position. Only the functions 
mark and dot return markers; the user may define ones that do and may assign 
markers to variables. If a marker is used in a context that requires an 
integer value then the ordinal of the position within the buffer is used; if a 
marker is used in a context that requires a string value then the name of the 
marked buffer is used. For example, if there has been assigned some marker, 
then (pop-to-buf fer there) will pop to the marked buffer. (goto-character 
there) will set dot to the marked position. 

A procedure written in MLlsp is simply an expression that is bound to a name. 
Invoking the name causes the associated expression to be evaluated. Invocation 
may be triggered either by the evaluation of some expression which calls the 
procedure, by the user typing it's name to the ESC-X command, or by striking a 
key to which the procedure name has been bound. 

All of the commands described in this manual may be called as MLisp 
procedures. Any parameters that they normally prompt the user for are taken as 
string expressions from the argument list in the same order as they are asked 
for interactivly . For example, the switch-to-buf fer command, which is normally 
tied to the ~XB key, normally prompts for a buffer name and may be called from 
MLisp like this: 

(switch-to-buf fer string-expression) 


12.2.3. Scope issues 

There are several sorts of names that may appear in MLisp programs. 
Procedure, buffer and abbrev table names are all global and occupy distinct 
name space. For variables there are three cases: 

1. Global variables: these variables have a single instance and are 
created either by using declare-global , set-default or setq-default . 

Their lifetime is the entire editing session from the time they 
are created. 
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2. Local variables: these have an instance for each declaration in a 
procedure body or local block (progn) . Their lifetime is the 
lifetime of the block which declares them. Local declarations nest 
and hide inner local or global declarations. 

3. Buffei — specific variables: these have a default instance and an 

instance for each buffer in which they have been explicitly given a 
value. They are created by using declare-buf fei — specific. When a 

variable which has been declared to be buffer specific is assigned a 
value, if an instance for the current buffer hasn't been created 
then it will be. The value is assigned to the instance associated 
with the current buffer. If a buffer specific variable is 
referenced and an instance doesn't exist for this buffer then the 
default value is used. This default value may be set with either 
setq-default or set-default. If a global instance exists when a 
variable is declared buffei — specific then the global value becomes 
the default. 


12.2.4. MLisp functions 

An MLisp function is defined by executing the defun function. For example: 

(defun 

(silly 

(insert-string ’’Silly! 5 ’) 

) 

) 

defines a function called silly which, when invoked, just inserts the string 
’’Silly!” into the current buffer. 

MLisp has a rather strange (relative to other languages) parameter passing 
mechanism. The arg function, invoked as (arg i prompt) evaluates the i'th 
argument of the invoking function if the invoking function was called 
interactivly or, if the invoking function was not called interactivly, arg uses 
the prompt to ask you for the value. Consider the following function: 

(defun 

( in-par ens 

(insert-string "(") 

(insert-string (arg 1 "String to Insert? ")) 

(insert-string ")”) 

) 

) 

If you type ESC-Xin-parens to invoke in-parens interactivly then Emacs will ask 
in the minibuffer "String to insert? " and then insert the string typed into 
the current buffer surrounded by parenthesis. If in-parens is invoked from an 
MLisp function by (in-parens "foo") then the invocation of arg inside in-parens 
will evaluate the expression "foo" and the end result will be that the string 
"(foo)" will be inserted into the buffer. 
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The function interactive may be used to determine whether or not the invoking 
function was called interactivly . Nargs will return the number of arguments 
passed to the invoking function. 

This parameter passing mechanism may be used to do some primitive language 
extension. For example, if you wanted a statement that executed a statement n 
times, you could use the following: 

(de fun 

(dotimes n 

(setq n (arg 1) ) 

(while (> n 0) 

(setq n (- n 1) ) 

(arg 2) 

) 

) 

) 

Given this, the expression (dotimes 10 (insert-string "<>")) will insert the 
string "<>" 10 times. [Note: The prompt argument may be omitted if the 

function can never be called interactivly] . 


12.2.5. Debugging 

The command debug enables debugging. It causes all following packages that 
are loaded to include special information for the debugger; it causes load to 
disregard any ".mo" files and always recompile the ".ml" file. The generation 
of debugging information can be disabled by typing "debug" again. Debuggable 
packages run slightly slower and take up more of Emacs' memory. The function 
"step-through FunctionName ' ' enables single stepping for the named function. 
When a single-stepped function is entered Emacs will single-step the execution 
of that function and all functions that it calls. When Emacs pauses while 
stepping through a function, the cursor will be in the function being stepped 
at the beginning of the function call that is about to be executed. You get to 
watch Emacs interprete your function. When Emacs has paused, the commands are: 

space Continue: execute this function, possibly stepping through the 

evaluation of any arguments. 

s Skip the trace of this function: execute it but turn off 

stepping within it . 

1 Look at the place where the traced function's "dot" is. 

p Print the value of some variable, 

r Enter a recursive-edit. 

~G Abort. 

Setting the variable single-step turns on stepping right then. Any uncaught 
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error will turn it off. "Don' t-step-through FunctionName ' ' disables stepping 
through functions. The variable compile-mlisp-debugging-hooks and the 
functions &step-through-arg-l and single-step-handler are magic. 

You can get a stack trace whenever an error occurs by setting the 
stack-trace-on-error variable. With this set, any time that an error occurs a 
dump of the MLisp execution call stack and some other information is dumped to 
the "Stack trace" buffer. 


12.3. A Sample MLisp Program 

The following piece of MLisp code is the Scribe mode package. Other 
implementations of Emacs, on ITS and on Multics have modes that influence the 
behaviour of Emacs on a file. This behaviour is usually some sort of 
language-specific assistance. In Unix Emacs a mode is no more that a set of 
functions, variables and key-bindings. This mode package is designed to be 
useful when editing Scribe source files. 


(defun 

The apply-look function makes the current word "look" 
different by changing the font that it is printed in. 
It positions dot at the beginning of the word so you 
can see where the change will be made and reads a 
character from the tty. Then it inserts "@c[" (where c 
is the character typed) at the front of the word and 
"]" at the back. Apply-look gets tied to the key ESC-1 
so typing ESC-1 i when the cursor is positioned on the 
word "begin" will change the word to "@i [begin] " . 
(apply-look go-forward 
(save-excursion c 

(if (! (eolp) ) (forward-character)) 

(setq go-forward -1) 

(backward-word) 

(setq c (get-tty-character) ) 

(if (> c ' ') 

(progn (insert-character * @ * ) 

(insert-character c) 

(insert-character '[') 

( forward-word) 

(setq go-forward (dot)) 

(insert-character ']') 

) 


) 


) 

(if (= go-forward (dot)) (forward-character)) 


) 


) 
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(defun 

This function is called to set a buffer into Scribe 
mode 

(scribe-mode 

(remove-all-local-bindings) 

If the string "LastEditDate=""" exists in the first 
2000 characters of the document then the following 
string constant is changed to the current date. The 
intent of this is that you should stick at the 
beginning of your file a line like: 

"@string(LastEditDate="Sat Jul 11 17:59:01 1981") . 
This will automatically get changed each time you edit 
the file to reflect that last date on which the file 
was edited. 

(if (! buffei — is-modified) 

(save-excursion 

(erroi — occurred 

(goto-character 2000) 

(search-reverse "LastEdi tDate=" " " ) 

(search- forward 
(set-mark) 

(search- forward """") 

(backward-character ) 

( de 1 et e-t o-k i 1 lbu f f er ) 

(insert-string (current-time)) 

(setq buffei — is-modified 0) 

) 

) 

) 

(local-bind-to-key " justify-paragraph" "\ei") 

(local-bind-to-key "apply-look" "\el") 

(setq right-margin 77) 

(setq mode-string "Scribe") 

(setq case- fold-search 1) 

(use-syntax-table "text-mode") 

(modi fy-syntax-entry "w — *") 

(use-abbrev-table "text -mode") 

(setq left-margin 1) 

(novalue) 

) 

) 

(novalue) 

12.4. Commands that deal with variables 
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declare-buf fei — specific variables. . .Expert 

Takes a list of variables and declares them to have buffei — specific values. 
A buffei — specific variable has a distinct instance for each buffer in existance 
and a default value which is used when new buffers are created. When a 
buffer-specific variable is assigned a value only the instance associated with 
the currently selected buffer is affected. To set the default value for a 
buffei — specific variable, use setq-default or set-default. Note that if you 
have a global variable which is eventually declared buffei — specific then the 
global value becomes the default. 


declare-global variables... Expert 

Takes a list of variables and for each that is not already bound a global 
binding is created. Global bindings outlive all function calls. 


print expression 

Print the value of the named variable. This is the command you use when you 
want to inquire about the setting of some switch or parameter. 


setq variable expression Expert 

Assigns a new value to a variable. Variables may have either string or 
integer values. (setq i 5) sets i to 5; (setq s (concat "a" "b") ) sets s to 
"ab". 


setq-default variable expression Expert 

Setq-default is used to set the default value of some variable. It can be a 
global parameter, a buffei — specific variable or a system variable. It makes no 
matter, setq-default will set the default. Setq-default is the command to use 
from within some MLisp program, like your start up profile (".Emacs pro"). For 
example, (setq-default right-margin 60) will set the default right margin for 
newly created buffers to 60. In previous versions of Emacs certain system 
variables had default versions from which default values were taken. So, to set 
the default value of right-margin one would assign a value to 
default-right-margin — but no more. Use setq-default (or set-default instead. 

The precise semantics of setq-default are: 

- If the variable being assigned to has not yet been declared, then 
declare it as a global variable. 

- If it is a global variable (whether or not the declaration was 

implicit) then assign the value to it just as the setq command would 

have done. 

- Otherwise, if the variable is buffer specific then set the default 

value for the variable. This will be used in all buffers where the 

variable hasn't been ejqplicitly assigned a value. Note that if you 

have a global variable which is eventually declared buffei — specific 
then the global value becomes the default. The intent of this is 
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that users should be able to put setq-default ' s in their .emacs_pro's 
without concerning themselves over whether the variable will 
eventually be a simple global or buffer-specific. 


set variable-name expression 

Set the value of some variable internal to Emacs. Emacs will ask for the 
name of a variable and a value to set it to. The variables control such things 
as margins, display layout options, the behavior of search commands, and much 
more. The available variables and switches are described elsewhere. Note that 
if set is used from MLisp the variable name must be a string: (set 
"left-margin" 77) . 


set-default variable-name expression 

This commands bears the same relationship to setq-default that set does to 
setq. It is the command that you use from the keyboard to set the default 
value of some variable. See the description of setq-default for more detailed 
information . 


is-bound variables... Expert 

an MLisp predicate that is true iff all of its variable name arguments are 
bound . 

12.5. Arithmetic Operators 


c= e e Expert 

1 2 

Returns true iff e is equal to e taking into account the character 

1 2 

translations indicated by case- fold-search. If word-mode-search is in effect, 
then upper case letters are "c=" to their lower case equivalents. 


! e e Expert 

1 2 

Returns not e . 

1 

!= e e Expert 

1 2 

Returns true iff e != e . 

1 2 

% e e Expert 

12 

Returns e % e (the C mod operator) . 

1 2 



& e e 
1 2 

Returns e & e . 

1 2 

* e e 
1 2 

Returns e * e . 

1 2 

+ e e 
1 2 

Returns e + e . 

1 2 

- e e 
1 2 

Returns e - e . 

1 2 

/ e e 
1 2 

Returns e / e . 

1 2 

< e e 
1 2 

Returns true iff e < e . 

1 2 


Expert 


Expert 


Expert 


Expert 


Expert 


Expert 


« e e Expert 

1 2 

Returns e << e (the C shift left operator) . 
1 2 

<= e e Expert 

1 2 

Returns true iff e <= e . 

1 2 

= e e Expert 

1 2 

Returns true iff e = e . 

1 2 

> e e Expert 

1 2 

Returns true iff e > e . 

1 2 
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>= e e Expert 

l 2 

Returns true iff e >= e . 

1 2 

>> e e Expert 

1 2 

Returns e » e (the C shift right operator) . 
12 

e e Expert 

1 2 

Returns e e (the C XOR operator) . 

1 2 

j e e Expert 

1 2 

Returns e | e . 

1 2 

12.6. Program Structure Commands 


defun (name expressions. ..)... Expert 

Defines a new MLisp function with the given name and a body composed of the 
given expressions. The value of the function is the value of the last 
expression. For example: 

(defun 

(indent-line ; this function just sticks a tab at 

(save-excursion ; the beginning of the current line 

(beginning-of-line) ; without moving dot. 

(insert-string " ") 

) 

) 

) 


exit-emacs ~C 
Exit Emacs. Will ask if you're sure if there are any buffers that have been 
modified but not written out. 


if test thenclause [ test thenclause ]* [ elseclause ]Expert 

Returns the value of thenclause iff test is true; otherwise it executes 
elseclause if it is present. For example: 

(if (eolp) 

(to-col 33) 

) 

will tab over to column 33 if dot is currently at the end of a line. 
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illegal-operation Expert 

Illegal-operation is bound to those keys that do not have a defined 
interpretation. Executing illegal-operation is an error. Most notably, "G, 
ESC-^G, ~X~G are bound to illegal-opetation by default, so that typing ~G will 
always get you out of whatever strange state you are in. 


nothing Expert 

Nothing evaluates the same as novalue (ie. it returns a void result) except 
that if it is bound to some key or attached to some hook then the key or hook 
behave as though no command was bound to them. For example, if you want to 
remove the binding of a single key, just bind it to "nothing”. 


novalue Expert 

Does nothing. (novalue) is a complete no-op, it performs no action and 
returns no value. Generally the value of a function is the value of the last 
expression evaluated in it's body, but this value may not be desired, so 
(novalue) is provided so that you can throw it away. 


progn expressions... Expert 

Evaluates the expressions and returns the value of the last expression 
evaluated. Progn is roughly equivalent to a compound statement (begin-end 
block) in more conventional languages and is used where you want to execute 
several expressions when there is space for only one (eg. the then or else 
parts of an if expression) . 


save-excursion expressions . . . Expert 

Evaluates the given expressions and returns the value of the last expression 
evaluated. It is much like progn except that before any expressions are 
executed dot and the current buffer are "marked" (via the marker mechanism) 
then after the last expression is executed dot and the current buffer are reset 
to the marked values. This properly takes into account all movements of dot 
and insertions and deletions that occur. Save-excursion is useful in MLisp 
functions where you want to go do something somewhere else in this or some 
other buffer but want to return to the same place when you're done; for 
example, inserting a tab at the beginning of the current line. 


while number expressions... Expert 

Executes the given expressions while the test is true. 

12.7. Dealing with Errors 



56 


erroj — message strings... Expert 

Sends the string-expressions to the screen as an error message where it will 
appear at the bottom of the screen. Emacs will return to keyboard level, 
unless caught by erroi — occurred. 


erroi — occurred expressions... Expert 

Executes the given expressions and ignores their values. If all executed 
successfully, erroi — occurred returns false. Otherwise it returns true and all 
expressions after the one which encountered the error will not be executed. 


stack-trace-on-error variable 

If ON Emacs will write a MLisp stack trace to the "Stack trace" buffer 
whenever an error is encountered from within an MLisp function (even inside an 
erroi — occurred) . 

12.8. Arguments 


argument-prefix ''U 

When followed by a string of digits A U causes that string of digits to be 
interpreted as a numeric argument which is generally a repetition count for the 
following command. For example, "'UlODOWN moves down 10 lines (the 10* th next). 
A string of n "U’s followed by a command provides an argument to that command 
n 

of 4 . For example, ~UD0WN moves down four lines, and ~U~UD0WN moves down 16. 
Argument-prefix should never be called from an MLisp function. 


prefix-argument-loop expressions. . .Expert 

(prefix-argument-loop <expresslons>) executes <expressions> prefix-argument 
times. Every function invocation is always prefixed by some argument, usually 
by the user typing ~Un. If no prefix argument has been provided, 1 is assumed. 
See also the command provide-pre fix-argument and the variable prefix-argument. 


provide-pre fix-argument number expressions .. .Expert 

(provide-pre fix-argument <value> <expression>) provides the prefix argument 
<value> to the <expression> . For example, the most efficient way to skip 
forward 5 words is : 

(provide-pre fix-argument 5 (forward-word)) 

See also the command prefix-argument-loop and the variable prefix-argument. 
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return-prefix-argument number Expert 

(return-prefix-argument n) sets the numeric prefix argument to be used by the 
next function invocation to n. The next function may be either the next 
function in the normal flow of MLisp execution or the next function invoked 
from a keystroke. Return-prefix-argument is to be used by functions that are 
to be bound to keys and which are to provide a prefix argument for the next 
keyboard command. 


prefix-argument variable 

Every function invocation is always prefixed by a numeric argument, either 
explicitly with "Un or provide-prefix-argument . The value of the variable 
prefix-argument is the argument prefixed to the invocation of the current MLisp 
function. For example, if the following function: 

(de fun 

(show- it 

(message (concat "The prefix argument is " prefix-argument)) 

) 

) 


were bound to the key "A then typing ''U^A would cause the message "The prefix 
argument is 4* ' to be printed, and ~U13~A would print "The prefix argument is 
13''. See also the commands prefix-argument- loop and provide-prefix-argument. 


prefix-argument-provided variable 

True iff the execution of the current function was prefixed by a numeric 
argument. Use prefix-argument to get it's value. 


arg number prompt Expert 

(arg i [prompt]) evaluates to the i'th argument of the invoking function or 
prompts for it if called interactively [the prompt is optional, if it is 
omitted, the function cannot be called interactivly] . For example, 

(arg 1 "Enter a number: ") 

Evaluates to the value of the first argument of the current function, if the 
current function was called from MLisp. If it was called interactively then it 
is prompted for. As another example, given: 

(defun (foo (+ (arg 1 "Number to increment? ") 1))) 

then (foo 10) returns 11, but typing "ESC-Xfoo" causes emacs to ask "Number to 
increment? " . Language purists will no doubt cringe at this rather primitive 
parameter mechanism, but what-the-hell . . . it's amazingly powerful. 
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argc Expert 

Returns the number of arguments that were passed to Emacs when it was invoked 
from the Unix shell. If either argc or argv are called early enough then 
Emacs' s startup action of visiting the files named on the command line is 
suppressed. 


argv i Expert 

Returns the ith argument that was passed to Emacs when it was invoked from 
the Unix Shell. If Emacs were invoked as "emacs blatto" then (argv 1) would 
return the string "blatto". If either argc or argv are called early enough 
then Emacs' s startup action of visiting the files named on the command line is 
suppressed. 


nargs Expert 

Returns the number of arguments passed to the invoking MLisp function. For 
example, within the execution of foo invoked by (foo x y) the value of nargs 
will be 2. 

12.9. Loading MLisp fucntions 


load file-name Expert 

Load reads the named file as a series of MLisp expressions and executes them. 
Typically a loaded file consists primarily of defun's and buffei — specific 
variable assignments and key bindings. Load is usually used to load macro 
libraries and is used to load ".emacs pro" from your home directory when Emacs 
starts up. 

For example, loading this file: 

(setq right-margin 75) 

(defun (my- line feed 

(end-of-line) 

(newl ine-and-indent) 

) 

) 

(bind-to-key "my-linefeed" 10) 

sets the right-margin to 75 and defines a function called my-linefeed and binds 
it to the linefeed key (which is the ascii character 10 (decimal)) 

The file name given to load is interpreted relative to the EPATH environment 
variable, which is interpreted in the same manner as the shell's PATH variable. 
That is, it provides a list of colon-separated names that are taken to be the 
names of directories that are searched for the named files. The default value 
of EPAIH searches your current directory and then a central system directory. 

MLisp programs get compiled into an efficiently interpreted byte code. (load 
"file") looks for both file. mo (MLisp object) and file. ml. If file. mo is 
missing or older than file. ml then file. ml is compiled and that is executed. 
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otherwise file. mo is simply executed. If file. ml gets compiled then Emacs 
attempts to write file. mo. Unless there are compilation errors, Emacs will be 
silent. 


autoload function-name file-name Expert 

(autoload command file) defines the associated command to be autoloaded from 
the named file. When an attempt to execute the command is encountered, the 
file is loaded and then the execution is attempted again, the loading of the 
file must have redefined the command. Autoloading is useful when you have some 
command written in MLisp but you don't want to have the code loaded in unless 
It is actually needed. For example, if you have a function named box-it in a 
file named box-it. ml, then the command (autoload "box-it" "box-it. ml") will 
define the box-it command, but won't load its definition from box-it. ml. The 
loading will happen when you try to execute the box-it command. 


auto-execute pattern function-name Expert 

Prompt for and remember a command name and a file name pattern. When a file 
is read in via visit-file or read-file whose name matches the given pattern the 
given command will be executed. The command is generally one which sets the 
mode for the buffer. Patterns must be of the form "*string" or "string*": 
"*string" matches any filename whose suffix is "string"; "string*” matches any 
filename prefixed by "string". For example, auto-execute c-mode *.c will put 
Emacs into C mode for all files with the extension ".c". 


execute-mlisp-buf fer Expert 

Parses the current buffer as as a single MLisp expression and executes it. 
This is what is generally used for testing out new functions: stick your 
functions in a buffer wrapped in a defun and use execute-mlisp-buf fer to define 
them. 


execute-mlisp-line string ESC-ESC 

Parses the string as an MLisp expression and executes it. 


execute-string string Expert 

Executes the characters from its string argument as though they had been 
typed at the keyboard. 

12.10. Command chaining 


previous-command Expert 

(previous-command) usually returns the character value of the keystroke that 
invoked the previous command. In is something like last-key-struck, which 
returns the keystroke that invoked the current command. However, a function 
may set the variable this-command to some value, which will be the value of 
previous-command after the next command invocation. This rather bizarre 
command/variable pair is intended to be used in the implementation of MLisp 
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functions which behave differently when chained together (ie. executed one 
after the other) . A good example is kill-to-end-of-line which appends the 
text from chained kills to the killbuffer. 

To use this technique for a set of commands which are to exhibit a chaining 
behaviour, first pick a magic number. -84, say. Then each command in this set 
which is chainable should (setq this-command -84) . Then to tell if a command 
is being chained, it suffices to check to see if (previous-command) returns 
-84. 

Did I hear you scream "hack''?? 


this-command variable 

The meaning of the variable this-command is tightly intertwined with the 
meaning of the function previous-command. Look at its documentation for a 
description of this-command. 

12.11. Getting input from the user 


get-tty-buf fer prompt Expert 

Given a prompt string it reads the name of a buffer from the tty using the 
minibuf and providing command completion. 


get-tty-character Expert 

Reads a single character from the terminal and returns it as an integer. The 
cursor is not moved to the message area, it is left in the text window. This 
is useful when writing things like query-replace and incremental search. 


get-tty-command prompt Expert 

(get- tty-command prompt) prompts for the name of a declared function (using 
command completion & providing help) and returns the name of the function as a 
string. For example, the expand-mlisp-word function is simply 

(insert-string (get- tty-command expand-mlisp-word ")). 


get-tty-string prompt Expert 

Reads a string from the terminal using its single string parameter for a 
prompt. Generally used inside MLisp programs to ask questions. 


get-tty-file prompt Expert 

Reads the name of a file from the terminal using its string parameter as a 
prompt. It should be used by MLisp functions whenever they need to ask for the 
name of a file. It does filename completion and gives help when the user asks 
for it . 
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get- tty-vari able prompt Expert 

(get-tty-variable prompt) prompts for the name of a declared variable (using 
command completion & providing help) and returns the name of the variable as a 
string. For example, the expand-mlisp-variable function is simply: 

(insert-string (get-tty-variable expand-mlisp-variable ")) 


getenv variable-name Expert 

(getenv "varname") returns the named shell environment variable. for 
example, (getenv "HOME”) will return a string which names your home directory. 

12.12. Dealing with column positioning 


current-column Expert 

Returns the printing column number of the character immediately following 
dot. 


current-indent Expert 

Returns the amount of whitespace at the beginning of the line which dot is in 
(the printing column number of the first non-whitespace character) . 


move-to-comment-column Expert 

If the cursor is not at the beginning of a line, ESC-C moves the cursor to 
the column specified by the comment-column variable by inserting tabs and 
spaces as needed. In any case, it the sets the right margin to the column 
finally reached. This is usually used in macros for language-specific 
comments . 


newline-and-indent LINEFEED 

Insert a newline, just as typing RETURN does, but then Insert enough tabs and 
spaces so that the newly created line has the same indentation as the old one 
had. This is quite useful when you're typing in a block of program text, all 
at the same indentation level . 


to-col number Expert 

Inserts tabs and spaces to move the following character to printing column n. 


comment-column variable 

The column at which comments are to start. Used by the language-dependent 
commenting features through the move-to-comment-column command. (default 33) 


12.13. Balancing parenthesis 
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backward-balanced-paren-line Expert 

Moves dot backward until either 

- The beginning of the buffer is reached. 

- An unmatched open parenthesis, ' (', is encountered. That is, 
unmatched between there and the starting position of dot. 

- The beginning of a line is encountered at "parenthesis level zero". 

That is, without an unmatched ')' existing between there and the 
starting position of dot. 

The definitions of parenthesis and strings from the syntax table for the 
current buffer are used. 


backward-paren Expert 

Moves dot backward until an unmatched open parenthesis, '(', or the beginning 
of the buffer is found. This can be used to aid in skipping over Lisp 
S-expressions . The definitions of parenthesis and strings from the syntax 
table for the current buffer are used. 


forward-balanced-paren-line Expert 

Moves dot forward until either 

- The end of the buffer is reached. 

- An unmatched close parenthesis, ')', is encountered. That is, 
unmatched between there and the starting position of dot. 

- The beginning of a line is encountered at "parenthesis level zero". 

That is, without an unmatched ' (' existing between there and the 
starting position of dot. 

The definitions of parenthesis and strings from the syntax table for the 
current buffer are used. 


forward-paren Expert 

Moves dot forward until an unmatched close parenthesis, ')*, or the end of 
the buffer is found. This can be used to aid in skipping over Lisp 
S-expressions. The definitions of parenthesis and strings from the syntax 
table for the current buffer are used. 

12.14. An easy way to write MLisp functions 

Often an MLisp function that you want to write can almost be expressed as a 
series of keystroke commands. A keyboard macro could amost be used, except 
that there might be a conditional needed. You can use the automatic MLisp 
function generation facility to generate the template for a function and then 
edit it. 
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gen-on name Expert "X [ 

Package generate. ml 

Enables the automatic generation of a function. Emacs will record all of the 
keys that you subsequently type and generate an MLisp function that is 
equivalent to them. Your keystrokes define the code for the function. 

For example, if you want to write a function that buts dot and mark around 
the whole buffer, just type ~X[, then the name of the function you wish to 
define. Now do the actions that you want the function to do: type ESC-<, 
and ESC->. This is all there is to the function, so type "X] . You'll be 

popped into a buffer that contains the new function, it will look like this: 

(defun (mark-whol e-buffer 

(beginning-of-file) 

(set-mark) 

(end-of-file) 

)) 


gen-off name Expert "X] 

Package generate. ml 

This terminates the generation of a function, it matches up with gen-on. 


start-generating-mlisp Expert 

Enables generation of MLisp code into the current buffer at dot. You 
probably aren't interested in this function, use gen-off and gen-on instead. 


stop-generating-mlisp Expert 

Disables the generation of MLisp. You probably aren't interested in this 
function, use gen-off and gen-on instead. 

12.15. Miscellaneous functions 


bobp Expert 

True iff dot is at the beginning of the buffer. 


bolp Expert 

True iff dot is at the beginning of a line. 


chai — to-string number Expert 

Takes a numeric argument and returns a one character string that results from 
considering the number as an ascii character. 
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concat strings... Expert 

Takes a set of string arguments and returns their concatenation. 


emacs-version Expert 

Returns a string that describes the current Emacs version. 


eobp Expert 

True iff dot is at the end of the buffer. 


eolp Expert 

True iff dot is at the end of a line. 


execute-extended-command ESC-x 

Emacs will prompt in the minibuffer (the line at the bottom of the screen) 
for a command from the extended set. These deal with rarely used features. 
Commands are parsed using a Twenex style command interpreter: you can type ESC 
or space to invoke command completion, or '?' for help with what you're allowed 
to type at that point. This doesn't work if it's asking for a key or macro 
name. 


expand-mlisp-variable Expert 

Prompts for the name of a declared variable then inserts the name as text 
into the current buffer. This is very handly for typing in MLisp functions. 
It's also fairly useful to bind it to a key for easy access. 


expand-ml isp-word Expert 

Prompt for the name of a command then insert the name as text into the 
current buffer. This is very handly for typing in MLisp functions. It’s also 
fairly useful to bind it to a key for easy access. 


following-char Expert 

Returns the character immediatly following dot. The null character (0) is 
returned if dot is at the end of the buffer. Remember that dot is not 'at' 
some character, it is between two characters. 


interactive Expert 

An MLisp function which is true iff the invoking MLisp function was invoked 
interactively (ie. bound to a key or by ESC-X) . 
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last— key— struck Expert 

The last command character struck. If you have a function bound to many keys 
the function may use last-key-struck to tell which key was used to invoke it. 
(insert-character (last-key-struck)) does the obvious thing. 


length string Expert 

Returns the length of its string parameter. (length "time") => 4. 


newline Expert 

Just inserts a newline character into the buffer — this is what the RETURN 
(~M) key 4-S generally bound to. 


newline-and-backup LINE INSERT 

Insert an end-of-line immedlatly after dot, effectivly opening up space. If 
dot is positioned at the beginning of a line, then "0 will create a blank line 
preceding the current line and position dot on that new line. 


preceding-char Expert 

Returns the character immedlatly preceding dot. The null character (0) is 
returned if dot is at the beginning of the buffer. Remember that dot is not 
'at* some character, it is between two characters. 


push-back-character number Expert 

Takes the character provided as its argument and causes it to be used as the 
next character read from the keyboard. It is generally only useful in MLisp 
functions which read characters from the keyboard, and upon finding one that 
they don't understand, terminate and behave as though the key had been struck 
to the Emacs keyboard command interpreter. For example, ITS style incremental 
search. 


push-back-string string Expert 

Takes the string provided as its argument and causes it to be used as the 
next characters read from the keyboard. It is generally only useful in MLisp 
functions which read characters from the keyboard, and upon finding some that 
they don’t understand, terminate and behave as though the keys had been typed 
to the Emacs keyboard command interpreter. 


quote string Expert 

Takes a string and inserts quote characters so that any characters which 
would have been treated specially by the reqular expression search command will 
be treated as plain characters. For example, (quote "a.b") returns "a\.b". 
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quote-character CHAR INSERT 

Insert into the buffer the next character typed without interpreting it as a 
command. This is how you insert funny characters. For example, to insert a ~L 
(form feed or page break character) type . This is the only situation 

where "G isn't interpreted as an abort character. 


recursion-depth Expert 

Returns the depth of nesting within recursive-edit's. It returns 0 at the 
outermost level . 


recursive-edit Expert 

The recursive-edit function is a call on the keyboard read/interpret/execute 
routine. After recursive-edit is called the user can enter commands from the 
keyboard as usual, except that when he exits Emacs by calling exit-emacs 
(typing ~C) it actually returns from the call to recursive-edit. This function 
is handy for packages that want to pop into some state, let the user do some 
editing, then when they're done perform some cleanup and let the user resume. 
For example, a mail system could use this for message composition. 


string-to-char string Expert 

Returns the integer value of the first character of its string argument, 
(string-to-char "0") = 'O'. 


substr string numbei — pos numbei — n Expert 

(substr str pos n) returns the substring of string str starting at position 
pos (numbering from 1) and running for n characters. If pos is less than 0, 
then length of the string is added to it; the same is done for n. 
(substr "kzin" 2 2 )— ''zi''; (substr "blotto. c" -2 2) = ".c". 


indent-C-procedure ESC-j 

Take the current C procedure and reformat it using the indent program, a 
fairly sophisticated pretty printer. Indent-C-procedure is God’s gift to those 
who don't like to fiddle about getting their formatting right. 

Indent-C-procedure is usually bound to ESC-j. When switching from mode to 
mode, ESC-j will be bound to procedures appropriate to that mode. For example, 
in text mode ESC-j is bound to justify-paragraph. 


justify-paragraph ESC-j 

Package justify. ml 

Takes the current paragraph (bounded by blank lines or Scribe control lines) 
and rejustifies all of the lines to that the first non-blank character is at 
left-margin and no line extends beyond right-margin. The left margin of the 
first line of the paragraph will be offset by paragraph-indent, 
justify-paragraph is usually bound to ESC-j when in text mode. 
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12.16. More on Invoking Emacs 

When Emacs Is invoked, it does several things that are not of too much 
interest to the beginning user. 

1. Emacs looks for a file called ".emacs pro'' in your home directory, 

if it exists then it is loaded, with the load command. This is the 

mechanism used for user profiles — in your .emacs pro file, place 
the commands needed to customize Emacs to suit your taste. If a 
user has not set up an .emacs pro file then Emacs will use a 
site-specific default file for initialization. At CMU this file is 
named /usr/local/lib/emacs/maclib/profile.ml 

2. Emacs will then interprete its command line switches. 

l<filename>” loads the given file (only one may be named) , 

,, -e<funcname>" executes the named function (again, only one may be 
named) . -1 and -e are executed in that order, after the user 
profile is read, but before and file visits are done. This is 
Intended to be used along with the csh alias mechanism to allow you 
to invoke Emacs packages from the shell (that is, assuming that 
there is anyone out there who still uses the shell for anything 
other than to run under Emacs!). For example: "alias rmail emacs 
-lrmail -ermail-com" will cause the csh "rmail" command to invoke 
Emacs running rmail. Exiting rmail will exit Emacs. 

3. If neither argv nor argc have yet been called (eg. by your startup 
or by the command line named package) then the list of arguments 
will be considered as file names and will be visited; If there are 
no arguments then the arguments passed to the last invocation of 
Emacs will be used. 

4. Finally, Emacs invokes it's keyboard command interpreter, and 
eventually terminates. 
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13. Keymaps 

When a user Is typing to Emacs the keystrokes are interpreted using a keymap. 

A keymap is just a table with one entry for each character in the ASCII 
character set. Each entry either names a function or another keymap. When the 
user strikes a key, the corresponding keymap entry is examined and the 
indicated action is performed. If the key is bound to a function, then that 
function will be invoked. If the key is bound to another keymap then that 
keymap is used for interpreting the next keystroke. 

There is always a global keymap and a local keymap, as keys are read from the 
keyboard the two trees are traversed in parallel (you can think of keymaps as 
FSMs, with keystrokes triggering transitions) . When either of the traversals 
reaches a leaf, that function is invoked and interpretation is reset to the 
roots of the trees. 

The root keymaps are selected using the use-global-map or use-local-map 
commands. A new empty keymap is created using the define-keymap command. 

The contents of a keymap can be changed by using the bind-to-key and 
local-bind-to-key commands. These two commands take two arguments: the name of 
the function to be bound and the keystroke sequence to which it is to be bound. 
This keystroke sequence is interpreted relative to the current local or global 
keymaps. For example, (bind-to-key "define-keymap" "VZd") binds the 

define-keymap function to the keystroke sequence '~Z' followed by 'd' . 

A named keymap behaves just like a function, it can be bound to a key or 
executed within an MLisp function. When it is executed from within an MLisp 
function, it causes the next keystroke to be interpreted relative to that map. 

The following sample uses the keymap to partially simulate the vi editor. 
Different keymaps are used to simulate the different modes in vi : command mode 
and insertion mode. 

(defun 

(insert-before ; Enter insertion mode 

(use-global-map "vi-insertion-mode") ) 

(insert-after ; Also enter insertion mode, but after 

; the current character 

( forward-character) 

(use-global-map "vi-insertion-mode") ) 

(exit-insertion ; Exit insertion mode and return to 

; command mode 

(use-global-map "vi-command-mode") ) 

(replace-one 

(insert-character (get-tty-character) ) 

(delete-next-character) ) 

(next-skip 

(beginning-o f- 1 ine) 



(next- line) 
(skip-white-space) ) 
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) 


(prev-skip 

(beginning-of-line) 

(previous-line) 

(skip-white-space) ) 

(skip-white-space 

(while (& ( ! (eolp) ) (| (= (following-char) ' ') (= (following-char 

(forward-character) ) ) 

(vi ; Start behaving like vi 

(use-globa 1-map "vi-command-mode") ) 


; setup vi mode tables 
(define-keymap "vi-command-mode") 

(define-keymap "vi- insert ion-mode") 

(use-global-map "vi-insertion-mode") ; Setup the insertion mode map 
(bind-to-key "execute-extended-command" "\"X") 

(progn i 

(setq i ' ') 

(while (< i 0177) 

(bind-to-key "self-insert" i) 

(setq i (+ i 1)))) 

(bind-to-key "self- insert" "\011") 

(bind-to-key "newline" "\015") 

(bind-to-key "self-insert" "\012") 

(bind-to-key "delete-previous-character" "\010") 

(bind-to-key "delete-previous-character" "\177") 

(bind-to-key "exit-insertion" "\033") 

(use-global-map "vi-command-mode") ; Setup the command mode map 
(bind-to-key "execute-extended-command" "\~X") 

(bind-to-key "next-line" "\~n") 

(bind-to-key "previous-line" "Vp") 

(bind-to-key "forward-word" "w") 

(bind-to-key "backward-word" "b") 

(bind-to-key "search- forward" "/") 

(bind-to-key "search-reverse" "?") 

(bind-to-key "beginning-of-line" "0") 

(bind-to-key "end-of-line" "$") 

(bind-to-key "forward-character" " ") 

(bind-to-key "backward-character" "\^h") 

(bind-to-key "backward-character" "h") 

(bind-to-key "insert-after" "a") 

(bind-to-key "insert-before" "i") 

(bind-to-key "replace-one" "r") 

(bind-to-key "next-skip" "+") 

(bind-to-key "next-skip" "\~m") 
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(bind-to-key "prev-skip" 

(use-global-map "default-global-keymap") 

13.1. Keymap Commands 


bind-to-key function-name keystroke-stringExpert 

Bind a named macro or procedure to a given key. All future hits on the key 
will cause the named macro or procedure to be called. The key may be a control 
key, and it may be prefixed by "X or ESC. For example, if you want ESC-= to 
behave the way ESC-Xprint does, then typing ESC-Xbind-to-key print ESC-= will 
do it. 


global-binding-of keystroke-stringExpert 

Returns the name of the procedure to which a keystroke sequence is bound in 
the global keymap. "nothing" is returned if the sequence is unbound. The 
procedure local-binding-of performs a similar function for the local keymap. 


local -bind-to-key function-name keystroke-stringExpert 

Prompt for the name of a command and a key and bind that command to the given 
key but unlike bind-to-key the binding only has effect in the current buffer. 
This is generally used for mode specific bindings that will generally differ 
from buffer to buffer. 


local-binding-of keystroke-string Expert 

Returns the name of the procedure to which a keystroke sequence is bound in 
the local keymap. "nothing" is returned if the sequence is unbound. The 
procedure global-binding-of performs a similar function for the global keymap. 


remove-all-local-bindings Expert 

Perform a remove-local-binding for all possible keys; effectively undoes all 
local bindings. Mode packages should execute this to initialize the local 
binding table to a clean state. 


remove-binding keystroke-string Expert 

Removes the global binding of the given key. Actually, it just rebinds the 
key to illegal-operation. 


remove-local-binding keystroke-stringExpert 

Removes the local binding of the given key. The global binding will 
subsequently be used when interpreting the key. Bug: there really should be 
some way of saving the current binding of a key, then restoring it later. 
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define-keymap keymap-name Expert 

Defines a new, empty, keymap with the given name. See the section on 
keymaps, 13 page 68, for more information. 


use-global-map keymap-name Expert 

Uses the named map to be used for the global interpretation of all key 
strokes. use-local-map is used to change the local Interpretation of key 
strokes. See the section on keymaps, 13 page 68, for more information. 


use- local-map keymap-name Expert 

Uses the named map to be used for the local interpretation of all key 
strokes. use-global-map is used to change the global interpretation of key 
strokes. See the section on keymaps, 13 page 68, for more information. 
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14. Region Restrictions 

The portion of the buffer which Emacs considers visible when it performs 
editing operations may be restricted to some subregion of the whole buffer. 

The narroitf-region command sets the restriction to encompass the region 
between dot and mark. Text outside this region will henceforth be totally 
invisible,, It won't appear on the screen and it won't be manipulable by any 
editing commands. It will, however, be read and written by file manipulation 
commands like read-file and write-current- file . This can be useful, for 

instance, when you want to perform a replacement within a few paragraphs: just 
narrow down to a region enclosing the paragraphs and execute replace-string. 

The widen-region command sets the restriction to encompass the entire buffer. 

It is usually used after a narrow-region to restore Emacs 's attention to the 
whole buffer. 

Save-restriction is only useful to people writing MLlsp programs. It is used 
to save the region restriction for the current buffer (and only the region 
restriction) during the execution of some subexpression that presumably uses 
region restrictions. The value of (save-restriction expressions...) is the 
value of the last expression evaluated. 


narrow-region Expert 

The narrow-region command sets the restriction to encompass the region 
between dot and mark. Text outside this region will henceforth be totally 
invisible. It won't appear on the screen and it won't be manipulable by any 
editing commands. This can be useful, for instance, when you want to perform a 
replacement within a few paragraphs: just narrow down to a region enclosing the 
paragraphs and execute replace-string. 


widen-region Expert 

The widen-region command sets the restriction to encompass the entire buffer. 

It is usualy used after a narrow-region to restore Emacs 's attention to the 
whole buffer. 


save-restriction expressions... Expert 

Save-restriction is only useful to people writing MLisp programs. It is used 
to save the region restriction for the current buffer (and only the region 
restriction) during the execution of some subexpression that presumably uses 
region restrictions. The value of (save-excursion expressions...) is the value 
of the last expression evaluated. 
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15. Mode Lines 

A mode line is the line of descriptive text that appears just below a window 
on the screen. It usually provides a description of the state of the buffer 
and is usually shown in reverse video. The standard mode line shows the name 
of the buffer, an if the buffer has been modified, the name of the file 

associated with the buffer, the mode of the buffer, the current position of dot 
within the buffer expressed as a percentage of the buffer size and and 

indication of the nesting within recursive-edit's which is shown by wrapping 

the mode line in an appropriate number of '[' '] ' pairs. 

It is often the case that for some silly or practical reason one wants to 

alter the layout of the mode line, to show more, less or different information. 
Emacs has a fairly general facility for doing this. Each buffer has associated 
with it a format string that describes the layout of the mode line for that 
buffer whenever it appears in a window. The format string is interpreted in a 
manner much like the format argument to the C printf subroutine. Unadorned 
characters appear in the mode line unchanged. The '%' character and the 
following format designator character cause some special string to appear in 
the mode line in their place. The format designators are: 

b Inserts the name of the buffer. 

f Inserts the name of the file associated with the buffer, 

m Inserts the value of the buffei — specific variable mode-string. 

M Inserts the value of the variable global-mode-string, 

p Inserts the position of "dot" as a percentage. 

* Inserts an if the buffer has been modified. 

[ Inserts (recursion-depth) x ['s. 

] Inserts (recursion-depth) '] 's. 

<c , | and > Think of them as "if", "else" and "endif". The "c" in "%<c" 

is a one letter condition code, capitalizing it negates the 
test. Text between "%<c" and "%>" will only appear in the mode 
line if the condition is satisfied. The possible conditions 
are : 

a 
b 

c 
e 

f 

1 

m 
n 

r 
t 


true iff abbrev mode is on. 

true iff this window is at the bottom of the 
screen . 

true iff case-fold-search is on 

true iff (recursion-depth) >0 (ie. if you're 
in the middle of a recursive-edit) 
true iff the first character of the buffer is 
visible in this window. 

true iff the last character of the buffer is 

visible in this window. 

true iff the buffer has been modified. 

true iff there is a region-restriction in 

effect on this buffer. 

true iff this buffer is read-only. 

true iff this buffer is in the top window. 


One very useful application of this is to include "%<L — 
More — %> which will cause the string " — More — " to appear in a 
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mode line if there is more text to be seen below the bottom of 
the window. 

If a number n appears between the '%' and the format designator then the 
inserted string is constrained to be exactly n characters wide. Either by 
padding or truncating on the right. 

At CMU the default mode line is built using the following format: 

" % [Buffer: %b%* File: %f %M (%m) %p%] " 

The following variables are involved in generating mode lines: 


global-mode-string variable 
Global-mode-string is a global variable used in the construction of mode 
lines see section 15, page 73 for more information. 


mode- line- format variable 
mode- line- format is a buffer specific variable used to specify the format of 
a mode line. See section 15, page 73 for more information. 


mode-string variable 
Mode-string is a buffer specific variable used in the construction of mode 
lines see section 15, page 73 for more information. 
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16. Syntax tables 


dump-syntax-table table-name Expert 

Dumps a readable listing of a syntax table Into a buffer and makes that 

buffer visible. 


modi fy-syntax-entry table-name syntax-specification Expert 

Modi fy-syntax-entry is used to modify a set of entries In the syntax table 
associated with the current buffer. Syntax tables are associated with buffers 
by using the use-syntax-table command. Syntax tables are used by commands like 
forward-paren to do a limited form of parsing for language dependent routines. 
They define such things as which characters are parts of words, which quote 
strings and which delimit comments (currently, nothing uses the comment 
specification) . To see the contents of a syntax table, use the 

dump-syntax-table command. 

Tiie parameter to modi fy-syntax-entry is a string whose first five characters 
specify the interpretation of the sixth and following characters. 

The first character specifies the type. It may be one of the following: 

'w' A word character, as used by such commands as forward-word and 

case-word-capitalize . 

space A character with no special interpretation. 

* (' A left parenthesis. Typical candidates for this type are the 

characters ’(', * [ * and Characters of this type also have 

a matching right parenthesis specified (')', * ] * and '}’ for 
example) which appears as the second character of the parameter 
to modi fy-syntax-entry . 

') ' A right parenthesis. Typical candidates for this type are the 

characters ')', ']' and '}'. Characters of this type also have 
a matching left parenthesis specified ('(', ' [' and for 
example) which appears as the second character of the parameter 
to modi fy-syntax-entry . 

' " ’ A quote character. The C string delimiters " and ' are usually 

given this class, as is the Lisp | . 

*V A prefix character, like \ in C or / in MacLisp. 

The second character of the parameter is the matching parenthesis if the 
character is of the left or right parenthesis type. If you specify that '(' is 
a right parenthesis matched by ' ) ', then you should also specify that ') ' is a 
left parenthesis matched by ' ('. 

The third character, if equal to says that the character described by 

this syntax entry can begin a comment; the forth character, if equal to ' }' 
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says that the character described by this syntax entry can end a comment . If 
either the beginning or ending comment sequence is two characters long, then 
the fifth character provides the second character of the comment sequence. 

The sixth and following characters specify which characters are described by 
this entry; a range of characters can be specified by putting a between 

them, a can be described if it appears as the sixth character. 


A few examples, to help clear up my muddy exposition: 


(modi fy-syntax-entry 

”w 

- M ) 

(modi fy-syntax-entry 

"(] 

[„) 

(modi fy-syntax-entry 

")[ 

]") 


; makes behave as a normal word 
; character (ESC-F will consider 
; one as part of a word) 

; makes ' [' behave as a left parenthesi 
; which is matched by ' ] ' 

; makes ']' behave as a right parenthes 
; which is matched by ' [' 


use-syntax-table table-name Expert 

Associates the named syntax table with the current buffer. See the 
description of the modi fy-syntax-entry command for more information on syntax 
tables . 
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17. Multiple Processes under Emacs 

Emacs has the ability to handle multiple interactive subprocesses. The 
following is a sketchy description of this capability. 

In general, you will not want to use any of the functions described in the 
rest of this section. Instead, you should be using one of the supplied 
packages that invoke them, see 20.13 page 93. For example, the "shell' ' 

command provides you with a window into an interactive shell and the "time' 1 
package puts the current time and load average (continuously updated) into the 
mode line. 

Multiple interactive processes can be started under Emacs (using 
"start-process” or "start-filtered-process") . Processes are tied to a buffer 
at Inception and are thereafter knovm by this buffer name. Input can be sent 
to a process from the region or a string, and output from processes is normally 
attached to the end of the process buffer. There is also the ability to have 
Emacs call an arbitrary MLISP procedure to process the output each time it 
arrives from a process (see "start-filtered-process") . 

Many of the procedures dealing with process management use the concept of 
"current-process" and "active-process". The current-process is usually the 
most recent process to have been started. Two events can cause the 
current-process to change: 

1. When the present current-process dies, the most recent of the 
remaining processes is popped up to take its place. 

2. The current-process can be explicitly changed using the 
"change-current-process" command . 

The active-process refers to the current-process, unless the current buffer 
is a live process in which case It refers to the current buffer. 

Below is list of the current mlisp procedures for using processes: 


active-process Expert 

Returns the name of the active process as defined in the section describing 
the process mechanism. 


change-current-process process-name Expert 
Sets the current process to the one named. 


continue-process process-name Expert 

Continue a process stopped by stop-process. 



current-process Expert 

Returns the name of the current process as defined in the section describing 
the process mechanism. 


eot-process process-name Expert 

Send an EOT to the process . 


insert-filter process-name function-nameExpert 

Insert a filtei — procedure between a process and Emacs. This function should 
subsume the start-flltered-process function, but we should retain that one for 
compatibility I suppose... 


insert-share-filter function-name Expert 

Provides the name of a filter procedure that will be called with IPC messages 
from the outside world. This allows programs that are run underneath Emacs to 
send messages to the Emacs that invoked them. For example, here is a trivial 
filter procedure 

(defun (share (execute-mlisp-line (process-output)))) 

which just takes IPC messages and executes them as MLisp expressions. Then 
(insert-share-filter "share") will cause it to catch IPC messages. 

As an example of how to invoke this beast from the outside here is a program 
which if run from a subshell within Emacs will cause Emacs to print "What the 
hell is a mlmsey tove?' ' in the mlnibuf. 

/* Demonstration of the IPC mechanisms that exist for processes 
to talk to containing Emaces */ 

#include <stdio.h> 


main () { 

register FILE *f; 
char buf[50]; 

f = fopen (EIPCname (buf) , "w") ; 
if (f=0) printf("No emacs IPC channel"); 
else { 

fprintf (f, "(message \"What the hell Is a mlmsey tove?\”) ") ; 
fclose (f) ; 

> 

> 

This just opens a channel to Emacs and writes a "message" command to it. All 
of the magic is in EIPCname (buf) , which constructs the name of the file to 
write to. Without any explaination, here it is: 
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/* Calculate the Emacs IPC file name (the name for the mpx file) for 
this "job". What is returns is "/tmp/EIPC_n” where n is the 
device number for the controlling tty. This number is obtained 
by magically looking into to U area. This only runs on 4.1BSD 
Unix. */ 

#include </usr/sys/h/param.h> 

#include </usr/sys/h/dir .h> 

#include </usr/sys/h/user .h> 

#define u (*( (struct user *) (char *) (0x80000000-UPAGES*NBPG) ) ) 

char *EIPCname (buf) 
char *buf; { 

register i; 

sprint f (buf, ”/tmp/EIPC_%o" , u.u_ttyd) ; 
return buf; 

> 


int-process process-name Expert 

Send an interrupt signal to the process. 


kill-process process-name Expert 

Send a kill signal to the process. 


list-processes Expert 

Analagous to "list-buffers". Processes which have died only appear once in 
this list before completely disappearing. 


process-filtei — name process-name Expert 

Returns the name of the filter procedure attached to some buffer. 


process-id process-name Expert 

Returns the process id of the process attached to some buffer. 


process-output Expert 

Called by an on-output-procedure to procure the output generated by the 
process whose name is given by MPX-process. Returns the output as a string. 


process-status process-name Expert 

Returns -1 if "process-name" isn't a process, 0 if the process is stopped, 
and 1 if the process is running. 
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quit-process process-name Expert 

Send a quit signal to the process. 


region-to-process process-name Expert 

Sends the characters in the region between dot and mark in the current buffer 
to the named process. When too many characters are sent to a process in one 
gulp, the send will be blocked until the process has removed sufficient 
characters from the buffer. The send will then be automatically continued. 
Normally this process is invisible to the Emacs user, but if the process has 
been stopped, the send will not be unblocked and further attempts to send to 
the process will result in an overwrite error message. 


reset-filter process-name Expert 

Removes the filter that had been bound to some process in a buffer. 


start-filtered-process shell-command-string process-name function-nameExpert 
Does the same thing as start-process except that things are set up so that 
"on-output-procedure" is automatically called whenever output has been received 
from this process. This procedure can access the name of the process producing 
the output by refer ing to the variable MPX-process, and can retrieve the output 
itself by calling the procedure process-output. 

The filter procedure must be careful to avoid generating 
side-effects (eg. search- forward) . Moreover, if it attempts to go to 
the terminal for Information, output from other processes may be 
lost. 


start-process shell-command-string process-nameExpert 

The home shell is used to start a process executing the command. This 
process is tied to the buffer "buffei — name" unless it is null in which case the 
"Command execution" buffer is used. Output from the process is automatically 
attached to the end of the buffer. Each time this is done, the mark is left at 
the end of the output (which is the end of the buffer) . 


stop-process process-name Expert 

Tells a process to stop by sending it a stop signal. Use continue-process to 
carry on. 


string-to-process process-name stringExpert 

The string is sent to the process, it's much like region-to-process. 
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si lent ly-kil 1-processes variable 

If ON Emacs will kill processes when it exits without asking any questions. 
Normally, if you have processes running when Emacs exits, the question "You 
have processes on the prowl, should I hunt them down for you" is asked, 
(default OFF) 


process-buffer — size variable 

Emacs does not allow process buffers to grow without bound. When a process 
buffer exceeds the value of the variable process-buffer — size, 500 characters 
are erased from the beginning of the buffer. The default value for 
process-buffer — size is 10,000. 

17.1. Problems 

The most obvious problem with allowing multiple interactive processes is that 
it is too easy to start up useless jobs which drag everyone down. Also when 
checkpointing is done, all buffers including the process buffers are 
checkpointed. So if you have a one line buffer keeping time, it will take more 
system time to checkpoint it than it will to keep it updated once a minute. 

In addition to anti-social problems, there are some real bugs remaining: 

- Sometimes when starting a process, it will inexplicably expire 
immediately. This often happens to the first process you fire up. 

- Subprocesses are assumed to not want to try fancy things with the 
terminal. Emacs doesn't know how to handle this and for now more or 
less ignores stty requests from processes. Someday, Emacs should try 
to handle stty's. 

- The worst problem is that background processes started outside Emacs 
can cause Emacs to hang when they finally finish. This might get 
fixed if I vrant to think about it. 

- If Emacs does crash or hang, you will find several orphan processes 
left hanging around. It is best to do a ps and get rid of them. 
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18. The Emacs database facility 

Unix Emacs provides a set of commands for dealing with databases of a rather 
primitive form. These databases are intended to be used in help facilities to 
find documentation for a given keyword, but they have many other uses: managed 
mailboxes or nodes in an info tree. 

A database is a set of (key, content) pairs which may be retrieved or stored 
based on the key. Both the key and the content may be arbitrary strings of 
characters. The content may be long, but there are restrictions on the 
aggr agate length of the keys. 

A database search list is a list of databases. When a key is looked up in a 
database search list the databases in the search list are examined in order for 
one containing the key. The content corresponding to the first key that 
matches is returned. When a key is to have its content changed only the first 
database in the search list is used. 

The commands available for dealing with databases are: 


extend-database-search-list dbname file-name Expert 

Adds the given data base file to the data base search list (dbname) . If the 
database is already in the search list then it is left, otherwise the new 
database is added at the beginning of the list of databases. 


fetch-database-entry dbname key Expert 

Takes the entry in the data base corresponding to the given key and inserts 
it into the current buffer. 


list-databases Expert 

Lists all data base search lists. 


put-database-entry dbname key Expert 

Takes the current buffer and stores it into the named database under the 
given key. 

There are four Unix commands provided for dealing with Emacs data bases 
(these are commands that you give to the shell, not Emacs) : 

1. dbadd — add entry to an Emacs data base 

dbadd dbname key 

2 . dbcreate — create an Emacs data base 

dbcreate dbname 


3. dblist 


list contents of an Emacs data base 



dblist dbname [ -1 ] [ -p ] newdbname 

4. dbprint — print an entry from an Emacs data base 
dbprint dbname key 

Dbadd adds the text from the standard input to the named database using the 
given key. Dbcreate creates the named database, making it empty. Dbprint 
prints the contents of the entry from the database with the given key. 

Dblist with no arguments simply lists the keys of all the items in the 
database. With the -1 option it prints some internal Information from the 
database of no interest to anyone but the implementor. The -p option causes 
the key and content of every entry to be listed as a shell command file which 
when executed will repeatedly invoke dbadd to rebuild the database. This form 
of dblist is handy when you want a readable ascii file representation of a data 
base for shipping around or editing. Databases should be recreated 
periodically to garbage collect them. 
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19 . Mode Packages 

The packages in this chapter describe some of the language specific modes 
available in Emacs . They are generally not invoked explicitly, but are 
associated with some file extension and loaded automatically when a file is 
read in (see auto-execute) . 

19.1. c-inode — simple assist for C programs 

begin-C-comment (ESC-') Initiates the typing in of a comment. Moves the cursor 
over to the comment column, inserts "/* " and turns on 

autofill. If ESC-' is typed in the first column, the the 
comment begins there, otherwise it begins where ever 
comment-column says it should. 

end-C-comment (ESC-’) Closes off the current comment. 

indent-C-procedure 

(ESC-j) Takes the current function (the one in which dot is) 
and fixes up its indentation by running it through the "indent" 
program. 

19.2. electric- lisp-mode — Assistance for Lisp programming 
No documentation yet. 

19.3. electric-c-mode — A more powerful C assistance package 

backward-paren (ESC- () Skips backward over the preceeding balenced set of 
parenthesis . 

begin-C-comment (ESC-') Used for entering a comment. Moves dot to the end of 
the line, tabs to the comment-column, and inserts "/* ". You 

can then type in a comment which will be autojustified to line 
up properly. End the comment with ESC-’. 

c-indent (ESC-j) Reindent the current function. Filters it through a 

prettyprinter called 'indent'. 

c-nl-indent (newline) Creates a new line which has the same indentation as 
the current line. If the current line ended with a '{' then 
the new line will be indented 4 more spaces. 

c-paren () , ] , >) Flashes the cursor to the corresponding open 

parenthesis, to show you which one you're closing off. In 
addition, for '}', if it's the only thing on the line then the 
indentation of the line will be adjusted to match the 
indentation of the line that contains the matchine 

edit-block-comment 

(ESC-e) Lets you edit a block comment that begins in the first 
column (position the cursor in such a comment and type ESC-e) . 

It restricts you view to just the text of the comment and 
changes the meaning of ESC-j to justify-paragraph. ~C exits 
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the block-comment editing and wraps the comment In a box of 
'*'s. 

end-C-comment (ESC- ' ) Terminates a comment . 

forward-paren (ESC-)) Skips forward over the following balenced set of 

parenthesis . 

19.4. scribe — weak assistance for dealing with Scribe documents 

Scribe mode binds justify-paragraph to ESC-j, defines appply-look and binds 
it to C-X-l, turns on autofill, sets the right margin to 77 and updates the 
LastEditDate to the current date. It also binds index-entry to ESC-I, and 
scribe-command to ESC-S. 

If the string "LastEditDate=" " exists somewhere in the first 2000 
characters of the document then then the region extending from it to the next 
is replaced by the current date and time. You're intended to stick in your 
document something like: 

©String (LastEditDate="Thu Jul 15 17:10:56 1982") 

Emacs will automatically maintain the date. The date will only change in the 
file you make some changes, the mere act of starting scribe-mode does not cause 
the date change to be permanent. 

Apply-look reads a single character and then surrounds the current word with 
"@c[" and "] " . So, if you've just typed "begin", typing ESC-l-i will 
change it to "@i [begin] " , which appears in the document as "begin". This 
use of the word "look" comes from the Bravo text editor. 

Index-entry takes a number of words and creates a Scribe index entry for that 
phrase, on a separate line. The current dot and mark are not modified. If the 
command is given with no prefix-argument, the current word is used as the index 
item. If a positive argument n is given, n words starting with the current 
word are used as the index phrase; a negative argument n causes the n words 
ending with the current word to be used. The easiest way to learn what the 
real rules are is to try it out; if you make a mistake, you can try again 
without having to change the cursor position, then delete the wrong index 
entries once you've got a right one. 

Scribe-command is used to create a Begin — End bracket pair for a specified 
scribe command. You are prompted for the name of the command (e.g.. Index, 
Itemize, Description, etc.) For example, ESC-S Itemize would insert 

@Begin (Itemize) 

@End (Itemize) 

and would leave the cursor on the blank line inside the begin — end brackets. 
If you always create scribe commands in this way, you'll never have unbalanced 
begin — ends in your scribe files. 
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19.5. text -mode — assist for simple text entry 

Implements the text-mode command which ties ESC-j to justify-paragraph and 
sets up autofill with a left margin of 1 and a right margin of 77. 
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20. Utility Packages 

This chapter contains a description of a few of the packages that have been 
written for Emacs in MLisp. To load some package, just type 

"ESC-X load PackageName' ' . The title of each following section contains the 
name of the package before the ' — '. The incremental-search package (20.8) and 
the killring package (20.11) are automatically loaded for TeleVideo 950 users. 

20.1. abbrev — define abbreviation for word in buffer 

abbreviate-word Prompts for an abbreviation for the current word. If a prefix 

argument is provided, the specified number of words are taken 
as the "word’ * to abbreviate. In any case, the minibuffer 
will show exactly what is being abbreviated. 

20.2. bb — bulletin boards 

The bulletin board package enables you to peruse notices on a bulletin board 
conveniently from within Emacs. The following commands may be used to maneuver 
within a bboard: 


F, N 
B, P 

space , return 


~S, S 
''R, R 
ESC-^S 
ESC— ^R 
T 

W, ~X~W 

~P 

M 

Q, ~C 
~X~C 

A 

ESC-ESC 


Go to the Next Bboard notice 
Go to the Previous Bboard notice 
See the body of the current notice 
Go to the Last notice on this Bboard 
Go to the First notice on this Bboard 
Search for a given string in this bboard 
Search in reverse for a string in this bboard 
Forward search within this notice only 
Reverse search within this notice only 

Type a file (in a new buffer) from some Ethernet machine 
Write the currently-displayed bboard onto a file 
Post a message on a bboard 
Send mail (small) 

Quit looking at this bboard 

Quit looking at all bboards for now 

Return to monitor 

Recursive edit, saving your bboard state 


This Emacs package keeps track of the most recent notice that you have looked 
at in each bboard, and starts you out each time with the first new message. If 
there aren't any new messages, then you will start at the end of the bboard. 
(If the bboard system was called automatically from your Emacs profile, or 
using the lObb program, then bboards without new messages will be skipped 
entirely. One difficulty, however: the lObb program does not exist.) 

The easiest way to automatically use the bboard package is to use the lObb 
program from your .profile or .login. If your .profile ends with a line like: 


lObb local general unix sports . . . 

then you will start up Emacs, reading the bboards first and being left in 
Emacs when you are done. If the first argument to lObb is "quiet" then you 
won't be asked about whether or not you want to check each bboard. If any of 
the arguments is "exit" then you will exit Emacs when you're done reading the 
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bboard. If any of the arguments is "shell" then you will go into a shell 
window when you are done reading the bboards. 

For those of you who like to tailor things more exactly to your liking, you 
can grub around with a few mlisp commands that are intended to be useful from 
your Emacs profile or from Emacs interactively. For example, the mlisp command 
"checkbboards" may be used to automatically update you with the new mesages on 
the bboards that interest you. Just put the lines 

(checkbboards "general" "local" <you fill in the list...> ) 

at or near the end of your .emacs_pro file. Then you will be updated every 
time you run Emacs. To look at a bboard when you're already within Emacs, you 
can use "ESC-X bb" . 

Please send all bug reports for this package to nsb@g. 

20.3. buff — one-line buffer list 

Loading the buff package replaces the binding for ^X-'B (usually 
list-buffers) with one-line-buf fei — list. 

one-line-buf fei — list 

Gives a one-line buffer list in the mini-buffer. If the buffer 
list is longer than one line, it will print a line at a time 
and wait for a character to be typed before moving to the next 
line. Buffers that have been changed since they were last 
saved are prefixed with an asterisk (*) , buffers with no 
associated file are prefixed with a hash-mark (#) , and empty 
buffers are prefixed with an at-sign (@) . 

20.4. Buffei — edit — a buffer management function 

This package provides a very nice buffer management package intended to 
replace the list-buffers function normally bound to , 'X / 'B. It pops up a window 
that contains a buffer listing, and lets you move around that buffer listing 
marking buffers for deletion, saving, unsaving, reverting, and so forth. This 
ability is incredibly useful when you are editing a big system that has all 
kinds of files all over the place, because it lets you move around freely from 
one file to another without having to remember or type buffer names. 

When buffei — edit is run, normally by typing ^X^B, it pops up a window whose 
contents is a buffer listing, sorted so that the file buffers come first, with 
the cursor positioned on the line corresponding to the buffer in which the 
command was executed. You can move the cursor from line to line in that buffer 
listing by using the ordinary cursoi — movement commands, or by using "n" for 
next and "p" for previous. When the cursor is positioned on a line 
corresponding to some buffer B, various commands can be typed that will change 
the disposition of B when the buffer is exited: 

d Delete the buffer. The buffer will be removed from the editor's 

tables using the Emacs delete-buffer command. This command will not 
write out a modified buffer, so that information will be lost if you 
delete a buffer with d. 
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c Close the buffer. The buffer will be written out to its attached file 

(if there is one) and then it will be deleted as with the d command. 

r Revert the buffer. If it is not a file buffer, nothing will happen. 

If it is a file buffer, then the current contents of the file will be 
read into the buffer, replacing its current contents. If you have 
made extensive modifications to a buffer and then decide that you 
want to start over again from the file copy, you can use this 
command. The buffer will not be deleted from Emacs' list of buffers. 

s Save the buffer. The buffer will be written out to its attached file, 

exactly as with the "X^S command. 

m Mark the buffer as unmodified. This will remove the "M" flag from the 

buffer listing, and mark the buffer as not in need of being saved, 
but will not actually write the buffer out to any file. 

u Unmark the buffer. Any action flag set by one of the above commands 

will be removed. 

In addition to those commands shown above that "mark" a buffer for processing 
when the buffer menu is exited, there are commands that have immediate action 
at the instant that they are typed: 

e Begin a recursive edit on the contents of the buffer. 

q Exit without processing. If you change your mind about all of the 

buffer operations you have flagged, you can go back and unmark them 
all by typing a u command for each one, or you can just type a q 
command, which will get you out of the buffer edit back to where you 
entered it from. 

g Exit and go to a buffer. This is the normal way of exiting from 

buffer-edit: you find the line corresponding to the buffer that you 
would like to edit next, and type g. All of the marks are processed, 
the various save, delete, and revert operations are performed, and 
the screen is filled with the contents of the indicated buffer. 

? Print some help text that includes a summary of these commands. 

20.5. capword — different behavior for word capitalizations 

The built-in Emacs functions case-word-upper, case-word- lower , and 
case-word-capita lize all leave the cursor where it began, and perform their 
operation on the word containing the cursor. Many people prefer to have these 
functions skip forward over a word after capitalizing or uncapitalizing it. 
These functions provide that service. 

The capword package defines three functions, upper — case-word, lower — case- 
word, and capitalize-word. Normally they are bound to ESC-u, ESC-1, and ESC-c 
respectively, though this package does not set up those bindings. 
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20.6. ciired — directory editor 

The dired package implements the dired command which provides some simple 
convenient directory editing facilities. When you run dired it will ask for 
the name of a directory, displays a listing of it in a buffer, and processes 
commands to examine files and possibly mark them for deletion. When you're 
through with dired it actually deletes the marked files, after asking for 
confirmation. The commands it recognizes are: 


d Marks the current file for deletion. A 'D* will appear at the 

left margin. It does not actually delete the file, it just 
marks it. The deletion will be performed when dired is exited. 
It also makes the next file be the current one. 

u Removes the deletion mark from the current file. This is the 

command to use if you change your mind about deleting a file. 
It also makes the next file be the current one. 

RUBOUT Removes the deletion mark from the line preceeding the current 

one. If you mark a file for deletion with 'd' the current file 
will be advanced to the next line. RUBOUT undoes both the 
advancing and the marking for deletion. 


e, v Examine a file put putting it in another window and doing a 

recursive-edit on it. To resume dired type ~C. 

r Removes the current file from the directory listing. It 

doesn't delete the file, it just gets rid of the directory 
listing entry. Use it to remove some of the clutter on your 
screen . 

q, ~C Exits dired. For each file that has been marked for deletion 

you v/ill be asked for confirmation. If you answer 'y' the file 
will be deleted, otherwise not. 


n, ~N Moves to the next entry in the directory listing, 

p, Moves to the previous entry in the directory listing. 

"V Moves to the next page in the directory listing. 

ESC-v Moves to the previous page in the directory listing. 

ESC-< Moves to the beginning of the directory listing. 

ESC-> Moves to the end of the directory listing. 

20.7. goto — go to position in buffer 


goto-line Moves the cursor to beginning of the indicated line. The line 
number is taken from the prefix argument if it is provided, it 
is prompted for otherwise. Line numbering starts at 1. 
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goto-percent Moves dot to the Indicated percentage of the buffer. The 

percentage is taken from the prefix argument if it is provided, 
it is prompted for otherwise. (goto-percent n) goes to the 
character that is n% from the beginning of the buffer. 

20.8. inci — search — ITS style incremental search 

ITS Emacs has a search command that is unusual in that it is "incremental''; 
it begins to search before you have finished typing the search string. As you 
type in the search string, Emacs shows you where it would be found. When you 
have typed enough characters to identify the place you want, you can stop. The 
inc i — search package perfectly emulates this in Unix Emacs. Typically one binds 
incremental -search to ~S and reverse-incremental-search to "R. 

The command to search is ~S (incremental-search) . "S reads in characters and 
positions the cursor at the first occurrence of the characters that you have 
typed. If you type ~S and then F, the cursor moves right after the first "F" . 
Type an "0", and see the cursor move to after the first "F0" . After another 
"0", the cursor is after the first "F00" after the place where you started the 
search. At the same time, the "F00" has echoed at the bottom of the screen. 

If you type a mistaken character, you can rub it out. After the F00, typing 
a rubout makes the "0" disappear from the bottom of the screen, leaving only 
"F0" . The cursor moves back to the "F0" . Rubbing out the "0" and "F" moves 
the cursor back to where you started the search. 

When you are satisfied with the place you have reached, you can type an ESC, 
which stops searching, leaving the cursor where the search brought it. Also, 
any command not specially meaningful in searches stops the searching and is 
then executed. Thus, typing ^A would exit the search and then move to the 
beginning of the line. ESC is necessary only if the next command you want to 
type is a printing character, Rubout, ESC or another search command, since 
those are the characters that would not exit the search. 

Sometimes you search for "F00" and find it, but not the one you expected to 
find. There was a second F00 that you forgot about, before the one you were 
looking for. Then type another ~S and the cursor will find the next F00. This 
can be done any number of times. If you overshoot, you can rub out the "S's. 
You can also repeat the search after exiting it, if the first thing you type 
after entering another search (when the argument is still empty) is a ~S . 

If your string is not found at all, the echo area says "Failing I-Search". 
The cursor is after the place where Emacs found as much of your string as it 
could. Thus, if you search for FOOT, and there is no FOOT, you might see the 
cursor after the F00 in FOOL. At this point there are several things you can 
do. If your string was mistyped, you can rub some of it out and correct it. 
If you like the place you have found, you can type ESC or some other Emacs 
command to "accept what the search offered". Or you can type ~G, which throws 
away the characters that could not be found (the "T" in "FOOT") , leaving those 
that were found (the "F00" in "FOOT") . A second ~G at that point undoes the 
search entirely. 

The ~G "quit" command does special things during searches; just what, depends 
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on the status of the search. If the search has found what you specified and is 
waiting for input, ~G cancels the entire search. The cursor moves back to 
where you started the search. If *G Is typed while the search is actually 
searching for something or updating the display, or after search failed to find 
some of your input (having searched all the way to the end of the file) , then 
only the characters which have not been found are discarded. Having discarded 
them, the search is now successful and waiting for more input, so a second "G 

will cancel the entire search. Make sure you wait for the first ~G to ding the 

bell before typing the second one; If typed too soon, the second ~G may be 
confused with the first and effectively lost. 

You can also type ~R at any time to start searching backwards. If a search 
fails because the place you started was too late in the file, you should do 
this. Repeated ~R's keep looking for more occurrences backwards. A ''S starts 
going forwards again. ~R's can be rubbed out just like anything else. If you 

know that you want to search backwards, you can use ~R instead of to start 

the search, because ~R is also a command (reverse-incremental-search) to search 
backward. 

20.9. ind-region — indent (slide) blocks of lines left or right 

The ind-region package provides a function that will move a block of text 
lines left or right, for manually meddling with indentation. The set of lines 
that it operates on is defined by point and mark, but in order to behave 
intuitively it doesn't quite use point and mark as a region. In particular, it 
will include the complete contents of any line if any character of that line 
falls in the marked region, and it will also include a line if the first 
character of that line is right after the end of the region. This behavior, 
while it sounds unusual, provides visual fidelity; if you set the mark anywhere 
on one line, and then move the point to anywhere on another line (including 
their beginnings or ends, respectively) , then those lines will be Included in 
the set of lines that is indented left or right. 

If no argument is provided, the function will assume an indentation of +4, 
which is a right shift of 4 spaces. In all cases, after the function has 
finished indenting a line it will compute the minimal sequence of tabs and 
spaces to effect the indentation. 

20.10. info — documentation reader 

Info is a system which lets you browse through the documentation for various 
systems. In particular, all the Emacs documentation is available online 
through it. Both the describe-command and describe-variable functions use it. 

Rather than document Info extensivly here, I suggest that you run Info and 
use it to describe itself. 

20.11. killring — fancy text killing package 

This package defines commands for killing and unkilling text. Commands to 
delete words. lines, and regions actually send the text to a ring of 
killbuffers, where they can be yanked back. Multiple killing commands in 
succession will concatenate text to the same buffer, so a single unkill can 
bring it all back. The unkill-pop command can cycle the kill ring to retrieve 
previously-killed stuff. 
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The following keys are redefined: 


"W 

kill-region 

ESC-w 

copy-region 


kill-lines 

ESC-k 

copy- lines 

ESC-d 

kill-word 

ESC-h 

backward-ki 1 1-word 

ESC-del 

backward-kill-word 

ESC-a 

append next kill (pretend previous 

"Y 

unkill 

ESC-y 

unkill-pop (kill the region, back 
unkill) 


command was ^K) 

up one on the kill ring. 


and 


There are usually four buffers in the killring. If you want more buffers in 
the ring (say 8) , execute the following mlisp functions BEFORE you load this 
file: 


(setq-default nrings 8) 

The function will behave pretty much the same as the old 
delete-to-end-of-line did, unless you want something better. The improved 
version bases its behavior on the horizontal position of the cursor at the time 
the command is issued. If the cursor is at the beginning of the line, the 
command will assume you want to kill the entire line, including the return at 
the end. If you're at the end of the line, then it will remove the return 
separating this line from the next. Otherwise, it will kill just to the end of 
the line. To get this function, execute the following mlisp functions after 
you load this file: 


(setq-default &kill-lines-magic 1) 


20.12. occur — find occurances of a string 

The occur package allows one to find the occurances of a string in a buffer. 
It contains one function 


Occurances When invoked, prompts with "Search for all occurances of: 

It then lists (in a new buffer) all lines contain the string 
you type following dot. Possible options (listed at the bottom 
of the screen) allow you to page through the listing buffer or 
abort the function . 

In addition, a global variable controls the action of the function: 

&Occurances-Extra-Lines 

is a global variable that controls how many extra surrounding 
lines are printed in addition to the line containing the string 
found. If this variable is 0 then NO additional lines are 

printed. If this variable is greater than 0 then it will print 
that many lines above and below the line on which the string 
was found. When printing more than one line per match in this 
fashion, it will also print a seperator of ' ' 
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so you can tell where the different matches begin and end. At 
the end of the buffer it prints '<«End of Occur>»'. 

20.13. process — high level process manipulation 

The process package provides high level access to the process control 

features of Unix Emacs. It allows you to interact with a shell through an 

Emacs window, just as though you were talking to the shell normally. 

shell The shell command is used to either start or reenter a shell 

process. When the shell command is executed, if a shell 
process doesn't exist then one is created (running the standard 
"sh'') tied to a buffer named "shell'. In any case, the 
shell buffer becomes the current one and dot is positioned at 
the end of it. In that buffer output from the shell and 
programs run with it will appear. Anything typed into it will 
get sent to the subprocess when the return key is struck. This 
lets you interact with a shell using Emacs, and all of it's 
editing capability, as an intermediary. You can scroll 
backwards over a session, pick up pieces of text from other 
places and use them as input, edit while watching the execution 
of some program, and much more... 

lisp The lisp command is exactly the same as the shell command 

except that it starts up "cmulisp' ' in the "lisp'' buffer. 
You can have both a shell and a lisp process going at the same 
time. You can even have as many shells going as you want, but 
this package doesn't support it. 

grab- last- line (ESC-=) This command takes the last string typed as input to 
the process and brings it back, as though you had typed it 
again. So if you muff a command, just type ESC-=, edit the 
line, and hit return again. 

1 isp-ki 1 1 -output 

("X^K) [this only applies to lisp processes] Erases the output 
from the last command. If you don’t want to see the output of 
the last command any more, just type and it will go away. 

(~M — return) Takes the text of the current line and sends it 
as input to the process tied to the current buffer. Actually, 
if dot is on the last line of the buffer, it takes the region 
from mark to the end of the buffer and sends it as input 
(output from a process causes the mark to be set after the 
inserted text) ; if dot is not on the last line, just the text 
of that line is shipped (presuming that your prompt is "$ ") . 

(~D) If dot is at the end of the buffer, then ~D behaves just 
as it does outside of Emacs — it sends an EOT to the 
subprocess (end of file to some folks) . If dot isn't at the 
end of the buffer, then it does the usual character deletion. 

send-int-signal (\177 — rubout) Sends an INT (Interrupt) signal to the 


pr-newline 


send-eot 
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subprocess, which should make it stop whatever it is doing. 


send-quit-signal 

(~\) Sends a QUIT signal to the subprocess, making it stop 
whatever it is doing and produce a core dump. 

20.14. pwd — print and change the working directory 

pwd Prints the current working directory in the mode line, just 

like the shell command "pwd''. 

cd Changes the current working directory, just like the shell 

command "cd' ' . You should beware that cd only changes the 
current directory for Emacs, if it has already spawned a 
subprocess (a shell, for example) then a cd from within Emacs 
has no effect on the shell. 

20.15. rmail — a mail management system 

Emacs may be used to send and receive electronic mail. The rmail command 
(Usually invoked as "ESC-Xrmail") is used for reading mail, small is used for 
sending mail. 


20.15.1. Sending Mail 

When sending mail, either by using the small command or from within rmail, 
Emacs constructs a buffer that contains an outline of the message to be sent 
and allows you to edit it. All that you have to do is fill in the blanks. When 
you exit from smail (by typing ~C usually — when you're editing the message 
body you will be in a recursive-edit) the message will be sent to the 
destinations and blindcopled to you. Several commands are available to help 
you in composing the message: 

justify-paragraph 

(ESC-j) Fixes up the line breaks in the current paragraph 
according to the current left and right margins. 

exit-emacs (’'C) Exits mail composition and attempts to send the mail. If 

all goes well the mail composition window will disappear and a 
confirmation message will appear at the bottom of the screen. 
If there is some sort of delivery error you will be placed back 
into the composition window and a message will appear. Bug: 
when delivery is attempted and there are errors in the 
delivery, the message will have been delivered to the 
acceptable addresses and not to the others. This makes 
retrying the message difficult since you have to manually 
eliminate the addresses to which the message has already been 
sent . 

mail-abort-send (~X~A) Aborts the message. If you're part-way through 

composing a message and decide that you don't want to send it, 
"'X'A will throw it away, after asking for confirmation. 
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mail-noblind-exit; 

(~X~C) Exits small and send the message, just as "C will, 
except that a blind copy of the message will not be kept. 


exit-emacs 


(~X~F) Same as ^C. 


exit-emacs 


(~X~S) Same as ~C. 


mail-append ( A Xa) Positions dot at the end of the body and sets margins and 
abbrev tables appropriatly . 


mail-cc 


(~Xc) Positions dot to the "cc:" field, creating it if 
necessary. 


mail-insert ( / 'X1) Inserts the body of the message that was most recently 
looked at with rmail into the body of the message being 
composed. If, for instance, what you want to do is forward a 
message to someone, just read the message with rmail, then 
compose a message to the person you want to forward to, and 
type ^Xi . 


mail-subject 

mail-to 


(~Xs) Positions dot to the "subject:" field of the message. 
(~Xt) Positions dot to the "to:" field of the message. 


20.15.2. Reading Mail 

The rmail command provides a facility for reading mail from within Emacs. 
When it is running there are usually two windows on the screen: one shows a 
summary of all the messages in your mailbox and the other displays the 
"current' ' message. The summary window may contain something like this: 


02621525335022 
B 02621525335030 
02621525335040 
02621525335072 
Ac 02621352421000 
c 02621353040000 
02621646433000 
B 02621647417000 
N 02622024522003 


29 Oct 1981 
29 Oct 1981 
31 Oct 1981 
3 Nov 1981 
3 Nov 1981 

3 Nov 1981 
[empty] 

4 Nov 1981 

5 November 


research ! dmr 
=>Unix-Wizards 
CSVAX.dmr 
EHF 
JIM 
=>JIM 
[empty] 

=>research ! ikey 
f laco 


[empty] 

A plea for understanding 
rc etymology 

fyi 

copyrights 
Re : copyrights 
[empty] 

Emacs 

cooking class 


This is broken into five columns, as indicated by the underlining. 


- The first column contains some flags: the cursor is at the current 
message, 'B' indicates that the message is a blindcopy (ie. A copy of 
a message that you sent to someone else) , 'A' indicates that you've 
answered the message, and 'N' indicates that the message is new. Any 
other characters in the third character position indicate mail 
classification. In the example above, two messages have been 
classified with the letter *c' . 
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- The second column contains a long string of digits that is internal 
information for the mail system. 

- The third contains the date on which the mail was sent. 

- The fourth contains the sender of the message, unless it is a 
blindcopy, in which case it contains the destination (indicated by 
the "=>") . 

- The fifth column contains the subject of the message. 

When in the summary window Rmail responds to the following commands: 

rmail-shell (!) Puts you into a command shell so that you can execute Unix 

commands. Resume mail reading by typing ~C. 

rmail- first-message 

(<) Look at the first message in the message file, 
rmai 1-last-message 

(>) Look at the last message in the message file, 
rmail-help (?) Print a very brief help message 

rmai 1-previous-page 

("B, ~H, b) Moves backward in the window that contains the 

current message. 

exit-emacs ("'C) Leave rmail. Changes marked in the message file directory 

(eg. deletions) will be made. 

rmail -next-page (''F, f) Moves forward in the window that contains the current 

message. To read a message that is longer than the window that 
contains it, just keep typing f and rmail will show you 
successive pages of it. 

rma i 1- f ind- f ir st-unseen-message 

~N Moves to the first new message flagged with 'N' in column 2 
of the header, and removes the ’N* . If no messages are so 
flagged, moves to the next message. 

rmai 1-search-reverse 

(~R) Prompts for a search string and positions at the first 
message, scanning in reverse, whose directory entry contains 
the string. 

rmai 1-search- forward 

(~S) Prompts for a search string and positions at the first 
message, scanning forward, whose directory entry contains the 
string. 


rma i 1 -wholeheader s 
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(~W) Toggle the wholeheaders bit. If this bit is off (the 
default) then the fields "via", "mail- from" , "origin", 

"received", and "message-id" will be suppressed in the message 
window . 

rmail-append (a) Append the current message to a file. 

rmail-classify (c) Prompts for a single character for classification of the 
current message. The character may not be numeric. 

rmai 1-delete-message 

(d, ~D) Flag the current message for deletion. It won't 

actually be deleted until you leave rmail. 

r ma i 1 - go t o-me s s a ge 

(g) Moves to the nth message. 

rmall-find-classified-message 

(1) Prompts for a single character and searches forward for the 
next message that has that classification. 

smail (m) Lets you send some mail. 

rmai 1-next-message 

(n) Moves to the next message. 

rmai 1-previous-message 

(p, ~P) Moves to the previous message. 

exit-emacs (q) the same as "'C 

rmail-reply (r) Constructs a reply to the current message, 

rmai 1-skip (s) Moves to the nth message relative to this one. 

rmail -unde 1 e t e-mes s a ge 

(u) If the current message was marked for deletion, u removes 
that mark. 

rmai 1-yank-message 

(y) Updates the display so that the current-message window 
contains the message at the position of dot In the directory 
window . 

20.16. scribe-bib — Scribe bibliography creation mode 

Scribe-bib mode provides a set of functions that create Scribe bibliography 
database entries. For each bibliography type scribe-bib mode provides a 
function that when executed prompts the user for appropriate fields and 
constructs a new entry of the proper type. The name of each of these functions 
is identical to the name of the corresponding bibliography type. Once the 
entry is created it can be edited using standard Emacs commands. The 
bibliography creation functions are Invoked by name using ESC-X and are listed 
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below: 


@article 

Create 

an 

©book 

Create 

an 

@booklet 

Create 

an 

@inbook 

Create 

an 

@incol lection 

Create 

an 

@inproceedings 

Create 

an 

@manual 

Create 

an 

@mastersthesis 

Create 

an 

@misc 

Create 

an 

©phdthesis 

Create 

an 

©proceedings 

Create 

an 

©techreport 

Create 

an 

©unpublished 

Create 

an 


©Article bibliography entry. 

@Book bibliography entry. 

©Booklet bibliography entry. 
@InBook bibliography entry. 
@InCollectlon bibliography entry. 
©InProceedings bibliography entry. 
@Manual bibliography entry. 
@MastersThesis bibliography entry. 
@Misc bibliography entry. 
©PhdThesis bibliography entry. 
©Proceedings bibliography entry. 
©TechReport bibliography entry. 
©Unpublished bibliography entry. 


20.17. spell — a simple spelling corrector 

The spell package implements the single function spell. It provides a simple 
facility for doing spelling correction. If you invoke spell it will scan your 
file looking for spelling errors, then it will go through a dialogue to let you 
fix them up. For each misspelled word Emacs will show you the word, some 
context around it and ask you what to do. If you type 'e* or '~G' the spelling 
corrector will exit. If you type ' * it will ignore the word. If you type V 
it will ask for the text to use in replacing the word and perform a 
query-replace. Bug: This uses the Unix spell command which believes that its 
input is a source for the Unix standard text formatter troff/nroff; Spell 
misbehaves on Scribe .mss files. 


20.18. srccom — source comparison function 

srccom Compare text in two windows. To begin the compar ison, place 

the dot at the beginning of one of the two pieces of text to be 
compared, switch to the other window, and place the dot at the 
beginning of the other piece of text. (If there are more than 
two windows, the two windows to be compared must be adjacent, 
and the dot must be left in the upper one.) When this command 

is invoked, it will search forward, stopping when either a 

difference is encountered or the end of the buffer is reached, 
case-fold-search governs comparison of case differences. The 
region is left around the equal portions in both windows. 

20.19. tags — a function tagger and finder 

The tags package closely resembles the tags package found in Twenex Emacs. 
The database used by the tag package (called a tagfile) correlates function 
definitions to the file in which the definitions appear. The primary function 
of the tag package is to allow the user to specify the name of a function, and 

then have Emacs locate the definition of that function. The commands 

implemented are: 

add-tag Adds the current line (it should be the definition line for 

some function) to the current tagfile. 
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goto-tag goto-tag takes a single string argument v/hich Is usually the 

name of a function and visits the file containing that function 
with the first line of the function at the top of the window. 
The string may actually be a substring of the function name 
(actually, any substring of the first line of the function 
definition) . If goto-tag is given a numeric argument then 
rather than asking for a new string it will use the old string 
and search for the next occurrence of that string in the 
tagfile. This is used for stepping through a set of tags that 
contain the same string. 

This is the most commonly used command in the tag package so it 
is often bound to a key: Twenex Emacs binds it to ESC-., but 
the Unix tag package doesn't bind it to anything, it presumes 
that the user will bind it (I use ^X"G) . 

make-tag-tab leTakes a list of file names (with wildcards allowed) and builds 
a tagfile for all the functions in all of the files. It 
determines the language of the contents of the file from the 
extension. This command may take a while on large directories, 
be prepared to wait. A common use is to type "make-tag-table 
*.c". 

recompute-all-tags 

Goes through your current tag file and for each file mentioned 
reflnds all of the tags. This is used to rebuild an entire tag 
file if you've made very extensive changes to the files 
mentioned and the tag package is no longer able to find 
functions. The tagfile contains hints to help the system 
locate the tagged function, as you make changes to the various 
files the hints become out of date. Periodically (no too 
often!) you should recompute the tagfile. 

visit-functionTakes the function name at or before dot, does a goto-tag on 
that name, then puts you into a recursive-edit to look at the 
function definition. To get back to where you were, just type 
"C. This is used when you're editing something, have dot 
positioned at some function Invocation, then want to look at 
the function. 

vislt-tag-tableNormally the name of the tagfile is ''.tags'' in the current 
directory. If you want to use some other tagfile, 

visit-tag-table lets you do that. 

20.20. time — a mode line clock 

This package only implements one usei — visible function, time, which puts the 
current time of day and load average (continuously updating!) in the mode line 
of each window. It uses global-mode-string and the subprocess control 
facility. Major! 
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20.21. transp — transpose words or lines 

The transp package allows transposition of word and lines (similar to the 
function of transpose-character.) 

transpose-word Takes the two words preceding dot and exchanges them. (If dot 

is within a word, it is counted as preceeding dot.) 

transpose-line Takes the two lines preceding dot and exchanges them. (If dot 

is within a line, it is counted as preceeding dot.) 

There are also several global variables to control the transpose-line 
function : 

&De f aul t-Tr anspose-Direct ion 

(default 1) Tells transpose-line which other line to transpose 
with the current on. If this is set to 1 (actually your 

favorite non-zero number will do) then transpose-line will use 

the line above the current one and if it is 0 transpose-line 

will use the line below the current one. 

&De f aul t-Tr anspose-Fol low 

(default 0) If this is set Non-zero it will cause 

transpose-line to leave the cursor (dot) on the line that got 
transposed, and if this is set to Zero it will stay at the same 
place in the file! 

&Def aul t-Tr anspose-Magic 

(default 0) This variable controls some magic inside the 
transpose Line function. If it is set to zero, transpose-line 
will behave as controlled by the settings of the above 
variables. If this is set Non-Zero then the magic is 
controlled by the cursor position when transpose-line is 
invoked. If the cursor (dot) is somewhere in the middle of a 
line, then it behaves as if this variable were 0. If the 
cursor is at the end of a line, or at the beginning of a line, 
the magic will happen. If the cursor is at the beginning of 
the line transpose-line will override the above variable 
settings and assert that you want to transpose with the above 
line and that you want to follow the line you were on. If the 
cursor is at the end of a line transpose- line will assume that 
you want to transpose with the next line and that you want to 
follow the line you were on. The main reason for this magic is 
so that you can blip lines up and down in your buffer real 
easily. 

20.22. writeregion — - write region to file 

This package only implements one function, write-region-to-file, which takes 
the region between dot and mark and writes it to the named file. 
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Unix Emacs Reference Card 
SOME NECESSARY NOTATION 

Any ordinary character goes 
into the buffer (no Insert 
command needed) . Commands 
are all control characters 
or other characters 
prefixed by Escape or a 
control-X. Escape is some- 
times called Meta or 
Altmode in EMACS. 

A control character. "F 
means "control F". 

ESC- A two-character command 

sequence where the first 
character is Escape. ESC-F 
means "ESCAPE then F". 

ESC-X string A command desig- 
nated "by hand” . "ESC-x 
read-file" means: type 

"Escape", then "x", then 
"read-file", then <cr>. 
dot EMACS term for cursor 

position in current buffer, 
mark An invisible set position 

in the buffer used by 
region commands . 

region The area of the buffer 
between the dot and mark. 
CHARACTER OPERATIONS 
LEFT Move left (Arrow) 

RIGHT Move right 

UP Move up 

DOWN Move down " 

CHAR DELETE Delete right 
DEL or RUBOUT 

Delete left 

A T Transpose previous 2 

characters (ht_ -> th_) 

"Q Literally inserts (quotes) 

the next character typed 

(e.g. "Q-~L) 

A U-n Provide a numeric argument 

of n to the command that 

follows (n defaults to 4, 
try "U-DOWN or "U"U-RIGHT) 
~M or CR newline 

"J or NL newline followed by an 
indent 

WORD OPERATIONS 
ESC-LEFT Move left 
ESC-RIGHT Move right 


ESC-d Delete word right 

ESC-DEL Delete word left 

ESC-c Capitalize word 

ESC-1 Lowercase word 

ESC-u Uppercase word 

ESC-" Invert case of word 

LINE OPERATIONS 

"A Move to the beginning of 

the line 

"E Move to the end of the line 

LINE INSERT Open up a line for typing 
LINE ERASE Kill from dot to end of 
line ( A Y yanks it back at 
dot) 

PARAGRAPH OPERATIONS 
ESC-[ Move to beginning of the 

paragraph 

ESC-] Move to end of the 

paragraph 

ESC-j Justify the current 

paragraph 
GETTING OUT 

"X-"S Save the file being worked 
on 

"X-"W Write the current buffer 

into a file with a dif- 
ferent name 

"X-"M Write out all modified 

files 

"X-"F Write out all modified 

files and exit 

"C or ESC-"C or "X-"C Finish by 
exiting to the shell 
ESC-! Recursively push (escape) 

to a new shell 

SCREEN AND SCREEN OPERATIONS 
"N Show next screen page 

"P Show previous screen page 

PAGE ERASE Redisplay screen 
"Z Scroll screen up 

ESC-Z Scroll screen down 

OR HOME Move the line dot is on 
to top of the screen 
ESC-, Move cursor to beginning of 

window 

ESC-. Move cursor to end of 

window 

"X-2 Split the current window in 

two windows (same buffer 
shown in each) 

"X-l Resume single window (using 

current buffer) 
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A X-d Delete the current window, 
giving space to window 
below 

"X-n Move cursor to next window 
"X-p Move cursor to previous 
window 

ESC-"V Display the next screen 
page in the other window 
~X-~Z Shrink window 
A X-z Enlarge window 
BUFFER AND FILE OPERATIONS 
~Y Yank back the last thing 
killed (kill and delete are 
different) 

' , X- / 'V Get a file into a buffer 
for editing 

A X- A R Read a file into current 
buffer, erasing old con- 
tents 

A X-*I Insert file at dot 
"X-"0 Select a different buffer 
(it must already exist) 

A X-B Select a different buffer 
(it need not pre-exist) 

A X-~B Display a list of available 
buffers 

ESC-^YInsert selected buffer at 
dot 

ESC-< Move to the top of the 
current buffer 

ESC-> Move to the end of the 
current buffer 
HELP AND HELPER FUNCTIONS 
General help key 

~G Abort anything at any time. 
ESC-? Show every command contain- 
ing string (try ESC-? para) 
ESC-X infoBrowse through the 

Emacs manual. 

A X A U Undo the effects of pre- 
vious commands . 

SEARCH 

~S Search forward 
~R Search backward 
REPLACE 

ESC-r Replace one string with 

another 

ESC-q Query Replace, one string 
with another 
REGION OPERATIONS 
Set the mark 

~X-~X Interchange dot and mark 
( i . e . go to the other end 


of the region) 

~W Kill region ("Y yanks it 

back at dot) 

MACRO OPERATIONS 

"X- ( Start remembering 

keystrokes, ie. start 
defining a keyboard macro 
~X-) Stop remembering 

keystrokes, ie. end the 

definition 

~X-e Execute remembered 

keystrokes, ie. execute the 

keyboard macro 
COMPILING (MAKE) OPERATIONS. 


A X- A E 

Execute the "make" (or 

other) command, saving out- 


put in a buffer 

Z 

< 

1 

X 

< 

Go to the next error in the 
file 

~X- ! 

Execute the given command, 
saving output in a buffer 

MAIL 

~X--r 

Read mail. 

~X-m 

Send mail 



Key to Binding Index 
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ESC-prefix 

ESC 

start-remembering 

"X-( 

1 ine-to-top-o f-window 

ESC-! 

stop-remembering 

"X- 

beginning-of-window 

ESC-, 

de 1 e te-othei — windows 

"X-l 

end-o f-window 

ESC-. 

split-current-window 

"X-2 

beginning-o f- f i le 

ESC-< 

swi tch-to-bu f fer 

"X-b 

end-o f- file 

ESC-> 

delete-window 

"X-d 

apropos 

ESC-? 

execute-keyboard-macro 

"X-e 

backward-sentence 

ESC-a 

small 

"X-m 

backward-word 

ESC-b 

next-window 

"X-n 

delete-next -word 

ESC-d 

previous-window 

"X-p 

forward-sentence 

ESC-e 

rmail 

"X-r 

execute-m 1 i sp- line 

ESC-ESC 

en 1 ar ge-window 

"X-z 

forward-word 

ESC-f 

list-buffers 

"X-"B 

delete-previous-word 

ESC-h 

exit-emacs 

"X-"C 

justify-paragraph 

ESC-j 

descr ibe-wor d- in-bu f f er 

"X— "D 

case-word-lower 

ESC-1 

write- file-exit 

"X— "F 

query-rep 1 ace-str ing 

ESC-q 

insert-file 

"X-"I 

case-word-upper 

ESC-u 

write-modified- files 

"X-"M 

previous-page 

ESC-v 

read-file 

"X— "R 

cute-extended-command ESC-x 

write-current- file "X- 

-"S 

scroll-one-line-down 

ESC-z 

new-undo 

"X-"U 

backward-paragraph 

ESC-f 

visit-file 

"X-"V 

forward-paragraph 

ESC-] 

write-named- file 

"X-"W 

case-word-invert 

ESC-" 

exchan ge-dot-and-mark 

"X-"X 

page-next-window 

ESC-"V 

shrink-window 

"X-"Z 

delete-reglon-to-buf fer 

ESC— "W 

yank- from-ki 1 lbu f fer 

"Y 

yank-buf fer 

ESC-"Y 

scroll -one- 1 ine-up 

"Z 

ert ESC-" " return-to- 

-monitor "_ 


set-mark 




beginning-o f- 1 ine 

"A 



b ackwar d-char ac t er 

"B 



delete-next-character 

"D 



end-o f- line 

"E 



forward-character 

"F 



illegal-operation 

"G, "X-' 

G, 


delete-previous-character 



newl ine-and-indent 

"J 



k i 1 1 - 1 o-end-o f- 1 ine 

"K 



redraw-display 

"L 



newline 

"M 



next- line 

"N 



newl ine-and-backup 

"0 



previous-line 

"P 



quote-character 

"Q 



search-reverse 

"R 



search- forward 

"S 



transpose-characters 

"T 



argument-prefix 

"U 



next -page 

"V 



delete-to-killbuf fer 

"W 



"X-prefix 

"X 



execute-monitoi — command 

"X- ! 
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* 53 

+ 53 

53 

.emacs_pro 51, 58, 67 

/ 53 

< 53 

« 53 

<= 53 

= 53 

> 53 

>= 54 

» 54 

54 
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Abbreviate-word 87 
Active-process 77 
Append 93 
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Apropos 7 , 41 
Arg 57 
Argc 58 

Argument-prefix 56 
Argv 58 
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Auto-execute 59 , 84 
Autoload 59 
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Backup-before-writing 25 
Backup-by-copying 25 
Backup-by-copying-when-linked 25 
Backward-balanced-paren-line 62 
Backward-character 9 
Backward-kil 1-word 93 
Backward-paragraph 9 
Backward-par en 62 

Backward-sentence 9 
Backward-word 9 
Baud-rate 40 
Bb 87 

Begin-C-comment 84 

Beginning-of-file 10 

Beginning-of-line 10 

Beginning-of-window 18 

Bibliography support for Scribe 

Bind-to-key 43, 44, 68, 70 

Bobp 63 

Bolp 63 

Buff 88 

Buffer list 88 

Buffer management function 88 

Buffer — edit 88 

Buffer — is-modified 17 

Buffer — size 16 

Buffer — specific 47, 51, 52 

Bulletin boards 87 

C= 52 

Case- fold-search 30, 52 
Case-region-capital ize 15 

Case-region-invert 15 
Case-region- lower 15 

Case-region-upper 15 
Case-word-capital ize 15, 75 

Case-word-invert 15 
Case-word- lower 15 

Case-word-upper 15, 89 
Cd 95 

Change-current-process 77 
Change-directory 40 
Char — to-string 63 

Checkbboards 87 
Checkpoint 25 
Checkpoint Files 25 
Checkpoint- frequency 25 

Clock 100 

Comment-column 61, 84 
Compare 99 
Compile-it 33, 34 
Compile-mlisp-debugging-hooks 49 
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Concat 64 
Continue-process 77 
Copy- lines 93 

Copy-region 93 
Copy-region-to-buf fer 
Ctlchai — with-~ 21 

Current-buf fei — name 16 

Current-column 61 
Current- file-name 24 
Current-indent 61 
Current-numeric-time 40 
Current-process 78 
Cur rent- time 40 

Debug 48 

Declare-buf fei — specific 47, 51, 52 

Declare-global 45, 46, 51 
Define-buf fei — macro 43, 44 

Def ine-global-abbrev 36, 37 
Define-hooked-global-abbrev 37 
Define-hooked-local-abbrev 37 
De fine-keyboard-macro 43, 44 
Define-keymap 68, 71 
Define-local-abbrev 36, 37 

De fine-string-macro 43, 44 

Defun 47, 54 
Delete-buffer 16 
Delete-next-character 12 
Delete-next-word 12 
Delete-othei — windows 18 

Delete-previous-character 12 
Delete-previous-word 12 
Delete-reg.ion-to-buf fer 12 
Delete-to-killbuf fer 12, 13, 14 
Delete-white-space 13 
Delete-window 18 
Deleting files 90 
Describe-bindings 7, 41 
Describe-command 7, 41 
Describe-key 7, 41 
Describe-variable 41 
Describe-word-in-buffer 41 
Directory 95 
Dired 90 

Display- file-percentage 40 
Don ' t-step-through 49 
Dot 14 

Dot-is-visible 18 
Dot-to-centre 19 
Dot-to-left-margin 19 
Dot-to-right-margin 19 
Dump-syntax-table 75 



Edit-macro 43, 44 
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Emacs-version 64 
End-C-comment 84 
End-of-file 10 
End-of-line 10 
End-of-window 18 
En large-window 18 
Eobp 64 
Eolp 64 
Eot-process 78 
Erase-buffer 13 
Erase-region 13 
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Erroi — occurred 56 

Exchange-do t-and-mark 13 
Execute-extended-command 64 
Execute-keyboard-macro 43, 44 
Execute-mlisp-buf fer 59 
Execute-mlisp-line 59 
Execute-monitoi — command 39 

Execute-string 59 
Exit-emacs 54 
Expand-file-name 24 
Expand-mlisp-variable 61, 64 
Expand-mlisp-word 60, 64 
Extend-database-search-list 82 

Fast-flltei — region 39 

Fetch-database-entry 82 
File-exists 24 
File-modtime 24 
Files-should-end-with-newline 
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